Call2Pay API Event offers our partners the ability to provide their customers with the Micropayment Call2Pay payment method while at the same time maintaining maximum control over their interaction with customers. When using the Call2Pay solution, the partner is responsible for displaying the required input forms and information to customers and for guiding customers through the payment process. As a maximum amount of 10 euros per drop charge can be booked in Germany as of 1 April 2008, the "Multicall" expansion mode is available, which makes it easier to settle larger amounts.
The payment process essentially consists of three steps:
Selection of the country from which the customer would like to call, and, if applicable, selection of the desired rate. Displaying the reserved Call2Pay telephone number with pricing information required by law, and a waiting function until the required call duration is complete. Sending confirmation of successful payment to the customer. As a maximum amount of 10 euros per drop charge can be booked in Germany as of 1 April 2008, the "Multicall" expansion mode is available, which makes it easier to settle larger amounts. If an amount larger than 10 EUR is requested for Germany, there are two options:
-
If Multicall is not desired:
The amount will be reserved for one call. Billing is conducted solely on a time-increment basis. This is also the mode for Call2Pay API Event 1.0
-
If Multicall is desired:
The total amount is split up between several calls (at the current maximum increment of 10 euros), with a final call for the remaining balance (if the payment amount is not evenly divisible by 10 euros).
For example: If 29.99 euros is requested, this amount is split among 3 calls (2 x 10 euros + 1 x 9.99 euros)
All Multicall calls have the same value for "handle".
All calls have the same value for "number". This means that the end customer should use the redial function repeatedly. In the statistics only one figure is displayed for the total amount.
See Example for an illustration of a typical payment transaction.
return to the top
In the following sections the syntax for the parameters and responses is described:
- name :type
Required parameter with parameter type - (name :type)
Optional parameter; if no value is entered an empty string (""), numerical zero (0) or logical false (0) will be read. - (name :type) =default value
Optional parameter; if no input is provided, the default value will be read. Important: If an empty string is inputted for the parameter, this will be used and not the default value. - name :type if: condition
Required parameter if the designated condition is applicable. - (name :type) if: condition
The parameter is optional if the condition is applicable, but otherwise has no relevance. - (name :type) =default value if: dependant
As with previous entry, but with a defined presetting. - name[n] :type
indexed parameter: name[0], name[1], ... name[n-1]; typically co-exists with a parameter with a value of n
2.1.2. Standard Parameters and Responses
Each query must be sent to a defined service URL with required parameters for the identification of the micropayment partner conducting the query. The standard parameters are valid for all functions and are not described further in the present text.
Parameters:
- accesskey :string
contains the partner's personal access key. This access key is generated automatically when the partner registers with the Micropayment system. The key can be viewed in the ControlCenter. - (testmode :boolean) =0
switches automatically to an internal test environment that the partner can use to test his implementation without the costs associated with using the payment system. Responses:
- error :integer
contains 0 when successful or delivers the error number of the failed call. - errormessage :string if: error <> 0
contains a more detailed description of the error in plain text.
In order to simplify error management, the error codes for the return message "error" are subdivided in four different classes, each with their own number group.
- Permanent server error 1xxx
In the case of this error class a permanent problem with the web service is usually at fault. Support should be informed if errors are received in this error class. - Temporary server error 2xxx
Errors of this type are also caused by the web service, but have a temporary cause such as maintenance work or insufficient resources. Fortunately, the customer can be told that the service is only temporarily unavailable. - Client error 3xxx
The application accessing the service is typically at fault when an error of this class is received. It is advisable to log such errors with the "errormessage" text in order to enable the appropriate modification of the application. To address this error, please consult the technical documentation or contact support. - User error 4xxx
This class includes all errors that typically result from false customer input, such as an incorrect password, etc. A detailed error description should be displayed for the user so that he/she can correct the input error. In this error class the cause can be related to the application, however, if the inputted values are incorrectly formatted, for example. The Appendix contains a summary of all error codes, causes, and tips for repair.
return to the top
The interface can be accessed at the address http://webservices.micropayment.de/public/c2p/v2/ and is referred to as the {service URL} in the rest of this document. The interface is currently implemented with the help of two alternative technologies.
2.1.4.1. SOAP Web Service
Functions and parameters are sent as a SOAP Envelope (HTTP method: POST) to the service URL. All parameters are contained in the following message structure:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2p="http://webservices.micropayment.de/public/call2pay/version2.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<c2p:{function}>
<param xsi:type="c2p:C2P{function}RequestTyp">
<{name} xsi:type="{type}">{value}</{name}>
<{name} xsi:type="{type}">{value}</{name}>
...
</param>
</c2p:{function}>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
If the request is successful, the response message contains the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2p="http://webservices.micropayment.de/public/call2pay/version2.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<c2p:{function}Response>
<return xsi:type="c2p:C2P{function}ResponseTyp">
<{name} xsi:type="{type}">{value}</{name}>
<{name} xsi:type="{type}">{value}</{name}>
...
</return>
</c2p:{function}Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
... Or, if the request is unsuccessful, a SOAP fault will be received with the standard response elements error and errormessage:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>{error value}</faultcode>
<faultstring>{errormessage value}</faultstring>
<faultactor></faultactor>
<detail></detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
return to the top
The webservice URL is expanded with a parameter list as an HTTP query string (GET method). The parameter action is designated for the function name:
http://{service-url}/?action={function}&{name}={value}&{name}={value}&...
The response values are returned line-by-line as name/value pairs in the response message:
error=0
{name}={value}
{name}={value}
...
In the case of an error, only the two standard response elements error and errormessagewill be returned:
error={error value}
errormessage={errormessage value}
The respective parameters and response-element values are URL coded. Special characters should be entered in accordance with ISO-8859-1.
return to the top
2.2.1. Determine Available Countries with country
This function determines a list of available countries based on a specific payment amount. Using this function, the customer can be offered a list of available countries and the customer's country of origin can be preselected.
Parameters:
- project :string
Description of the project for which payment should be initiated - (amount :integer)
Indicates the amount that the customer should pay in the smallest unit of the requested currency (i.e. cents). If this parameter is empty, the amount specified in the project settings will be used by default. The amount is then converted for every country into its local currency and a check is conducted to see if a telephone number is available for this amount. - (currency :string(3)) ="EUR" if: amount has been indicated
Designates the currency of the value in the amount parameter. - (ip :string)
With this function, the preferred country can be simultaneously determined based on the customer's IP address (reponse: ipcountry and ipprovider). Response:
- countrycount :integer
Contains the number of identified countries and the returned country[n] values. - country[n] :string(2) if: countrycount > 0
Delivers country codes (e.g. "DE" for Germany and "AT" for Austria) for countries in which the converted price can be paid. - ipcountry :string(2) if: ip has been indicated
Contains the country in which the customer's indicated IP address is hosted. This is not necessarily the customer's country of origin, but the probability here is high. The returned value is not necessarily contained in the country list. - ipprovider :string if: ip has been indicated
-
This parameter indicates the customer's ISP, if ascertainable. Possible values:
"UNKNOWN" = ISP is not known, but is based in ipcountry
"AOL" = IP is in AOL's network, but the customer may originate from any other country. ipcountry usually contains "US"
An overview of all parameters and responses is provided by the Quick Reference Chart.
return to the top
2.2.2. Reserve Telephone Number with init
A new payment transaction is started with this function. A telephone number is reserved and then displayed for the customer. The customer should then be requested to call this number.
Parameters:
- project :string
Description of the project for which payment should be initiated. - (projectcampaign :string)
Indicates which project campaign this transaction should be assigned to. - (account :string)
Account number or designated name of the participating webmaster. The account of the project owner is used by default. - (webmastercampaign :string)
-
Designates the webmaster campaign the transaction should be assigned to.
- sessionid :string
A unique ID that identifies the customer session. This is saved for the open transaction. If the payment transaction is started a second time, the same telephone number will be displayed for the customer. - ip :string
The IP of the customer who has initiated the transaction. The customer IP is saved for later error diagnostics and is also used to prevent flooding attacks. - country :string(2)
The country of the caller, in order to offer the customer a national service number. - (language : string(2))
-
Defines the language of the telephone message. The standard language based on the country parameter is used by default.
- (amount :integer)
-
Indicates the amount the customer must pay in the lowest denomination of the requested currency (i.e. cents). If this parameter is empty, the amount specified in the project settings will be used as a default value.
Attention: The payment amount to be displayed to the customer and associated currency depends on the selected country setting in country. The payment amount is calculated as required based on the values which have been sent. The payment amount is then returned by the function.
- (currency :string(3)) ="EUR" if: amount has been indicated
-
Designates the currency of the amount parameter.
- (title :string)
Identifies the item to be purchased (e.g. customer number, user name, product description, etc.). This is displayed in the partner's statistics. If the paramter is left empty, the standard product in the project settings will be used. - (freeparam :string)
-
Combines a desired text with the transaction. The parameter can be retrieved again with other functions. This parameter can be an external partner ID or multiple values seperated by commas.
- multicall :integer
-
0 = Multicall not desired (default)
1 = Multicall desired
Response:
- status :string(20)
-
The reservation status of the transaction. In the case of an error, the two standard response elements error and errormessagewill be returned: Possible values are:
"INIT" = A new transaction has been initiated.
"REINIT" = An interrupted transaction has been reinitiated or a Multicall call has been completed.
"CALL" = The customer is calling at the moment
- handle :string(50)
The unique ID of the transaction. This is required by other functions for the retrieval of current status information. - expire :datetimestring
-
Point in time when reservation expires and the number is no longer valid. The time period is kept short (30 sec.) in order to conserve the inventory of telephone numbers. The status function is checked cyclically and the life span of the reservation refreshed accordingly.
- number :string
Delivers the service number to be called by the customer. The number is already optically formatted. - (numberinfo :string)
Contains, if required by law, additional information about rates and the displayed number. The text should be displayed immediately with the telephone number and linked visually with the number itself; for example, with the use of the star symbol (*) as a footnote. - origin :string
-
Indicates if the returned number can only be reached through a specific network (mobile or fixed-line network). This can occassionally occur. Typically, this response contains the value "BOTH". Notification should be provided to the customer if there is a limitation concerning the telephone network from which he/she can call (e.g. "Number can only be dialed from a landline").
"BOTH"
"LANDLINE"
"MOBILE"
- amount :integer
Amount that the customer pays for the entire call. This amount should be displayed to the customer along with numberinfo and currency. - currency :string
-
Designates the currency of payment amount in the amount response.
- mode: string
-
This response defines the telephone number's mode.
"DIRECT" = The number is unique and reserved for the customer. The customer can only be assigned by calling.
"DTMF" = Occassionally—typically in the case of foreign numbers—a DDI (Direct Dialing In) number cannot be reserved. When this occurs, the customer must identify him or herself with a TAN entered through the dialling pad during the call.
- tan :string if: mode = "DTMF"
-
The TAN to be entered by the customer via telephone in the "DTMF" mode.
- duration : integer
Total length of the call in seconds. - durationpart :integer
Previous call duration in seconds. This is zero when the status is "INIT"; larger than zero when the status is "REINIT" or "CALL"; and smaller than "duration" (see durationpart in status function) - split :integer
-
The same format as the parameter "amount".
If "split" > 0, the current transaction is a Multicall and the amount of the current call in cents is indicated.
Depending on "split", "numberinfo" is also formatted accordingly. In the prior example the following response would returned for the first init query:
"split" => 1000
"amount" => 2999
"numberinfo" => 10.00 euros/call from a German landline; charges may vary from a mobile network.
The response for the last query would be as follows:
"split" => 999
"amount" => 2999
"numberinfo" => 9.99 euros/call from a German landline; charges may vary from a mobile network.
- paid :integer
-
The same format as the parameter "amount".
Contains the total amount of previous (completed) Multicall calls.
- callcnt :integer
Number of successfully completed Multicall calls An overview of all parameters and responses is provided by the Quick Reference Chart.
return to the top
2.2.3. Call Monitoring with status
This function determines the current status of a reservation. This function should be queried on a cyclical basis in order to (1) maintain the reservation and (2) determine if the customer is currently calling or has already called. In addition, the progress made in a time-dependant call can be displayed for the customer—for example, with an AJAX solution.
Parameters:
- handle :string(40)
The transaction ID from the init function. Response:
- status :string(20)
-
The reservation status of the transaction. In the case of an error, the two standard response elements error and errormessagewill be returned: Possible values are:
"INIT" = Reservation is awaiting a call.
"REINIT" = Reservation is awaiting a call after an interruped connection.
"CALL" = The customer is calling at the moment
"RECALL" = The call was ended prematurely; the customer must call again in order to complete payment. If the case of this vaue, the init function must be queried again with the same values, as a new service number can be reserved again, among other things.
"COMPLETE" = Call was completed and successful. This status is only returned immediately after the completion of the call (for approx. 10 min.). Afterwards, the function returns an error for the queried handle. The properties of the transaction can be determined at any time, however, with info.
- expire :datetimestring
-
Point in time when reservation expires and the number is no longer valid. When this function is queried repeatedly the value is continually refreshed. (see expire explanation for init function)
- (caller :string) if: status <> "INIT"
Delivers the telephone number of the caller during and after a call, provided this number is identifiable. The telephone number is always shown in abbreviated form (for example: "01719988XXX") - (origin :string)
-
Contains the network of origin during or after the call, irrespective of "caller". With foreign numbers, the network of origin usually cannot be determined, and the reponse is empty.
"LANDLINE"
"MOBILE"
- duration :integer
Total length of the call in seconds. During a call, this value can deviate from the value in the init function, for example, when the customer is calling from a mobile network. - durationpart :integer
Call length still required in seconds. When the status is "CALL" or "RECALL", this value is typically smaller than duration. Thus, a percent value can be determined by comparing durationpart and duration, allowing a progress bar to be displayed for the customer. This value is 0 when the status is "COMPLETE". - (freeparam :string)
Contains the value that has been transferred by the init function. - split :integer
-
The same format as the parameter "amount".
If "split" > 0, the current transaction is a Multicall and the amount of the current call in cents is indicated.
Depending on "split", "numberinfo" is also formatted accordingly. In the prior example the following response would be returned for the first init query:
"split" => 1000
"amount" => 2999
"numberinfo" => 10.00 euros/call from a German landline; charges may vary from a mobile network.
The response for the last query would be as follows:
"split" => 999
"amount" => 2999
"numberinfo" => 9.99 euros/call from a German landline; charges may vary from a mobile network.
- paid :integer
-
The same format as the parameter "amount".
Contains the total amount of previous (completed) Multicall calls.
- callcnt :integer
Number of successfully completed Multicall calls An overview of all parameters and responses is provided by the Quick Reference Chart.
return to the top
2.2.4. Detailed Status Query with info
In contrast to the status function, this function returns all properties for a payment transaction. In addition, with this function expired reservations as well as successful and unsuccessful payment transactions can be retrieved. This function should not be queried on a cyclical basis (for example, when waiting for a call), as it requires a considerably higher reponse time and burdens the system. With this function, for example, a payment transaction can be verified before the customer makes use of the purchased service.
Parameters:
- handle :string(40)
The transaction ID from the init function. Response:
- status :string(20)
-
The status of the transaction. Possible values are:
"INIT" = Reservation is awaiting a call.
"REINIT" = Reservation is awaiting a renewed call after a previously interruped call.
"EXPIRED" = Reservation has expired without a call.
"CALL" = The customer is calling at the moment
"RECALL" = The call was ended prematurely; the customer must call again in order to complete payment.
"FAILED" = Call was ended prematurely; reservation has also expired.
"COMPLETE" = Call was completed and successful.
If no transaction is found under handle, error and errormessage will be returned.
- expire :datetimestring
-
The point in time at which the reservation expired or will expire. In contrast to the status function, an existing reservation is not refreshed by this function.
- project :string
Name of project sent in init query - projectcampaign :string
Indicates the campaign to which the transaction has been assigned - account :string
Indicates the account number or designated name of the particpating webmaster/project operator that has been sent - webmastercampaign :string
-
Webmaster's campaign
- country :string(2)
The initialized country of the caller - number :string
Delivers the reserved service number for the transaction. If the transaction has been completed, the number may no longer be called, as this number may have already been reserved for another customer. - amount :integer
The total payment amount for the call - currency :string
-
The currency in which the amount is designated.
- mode: string
The mode of the "DIRECT" or "DTMF" payment transaction from the init function - tan :string if: mode = "DTMF"
-
The TAN for the "DTMF" mode.
- (caller :string) if: status >= "CALL"
Delivers the telephone number of the caller during and after a call, provided this number is identifiable. The telephone number is always shown in abbreviated form (for example: "01719988XXX") - (origin :string)
-
Contains the network of origin during or after the call, irrespective of "caller". With foreign numbers, the network of origin usually cannot be determined, and the reponse is empty.
"LANDLINE"
"MOBILE"
- duration : integer
Total length of the call in seconds. - durationpart :integer
-
The elapsed call time so far.
- title :string
The product description for this transaction. - (freeparam :string)
Contains the value that has been sent by the init function. - split :integer
-
The same format as the parameter "amount".
If "split" > 0, the current transaction is a Multicall and the amount of the current call in cents is indicated.
Depending on "split", "numberinfo" is also formatted accordingly. In the prior example the following response would be returned for the first init query:
"split" => 1000
"amount" => 2999
"numberinfo" => 10.00 euros/call from a German landline; charges may vary from a mobile network.
The response for the last query would be as follows:
"split" => 999
"amount" => 2999
"numberinfo" => 9.99 euros/call from a German landline; charges may vary from a mobile network.
- paid :integer
-
The same format as the parameter "amount".
Contains the total payment when all previous (completed) Multicall calls are added up.
- callcnt :integer
Number of successfully completed Multicall calls. An overview of all parameters and responses is provided by the Quick Reference Chart.
return to the top
2.2.5. Simulated Call with testcall
The testcall function can be helpful during the integration of the web service and for testing purposes. It allows a customer call to be simulated, and is therefore only available in the test mode. If a payment transaction has been started with init in the test mode, the status can be set to "CALL", "RECALL" or "COMPLETE" with a separate query in order to test the functionality of the application.
- testmode :boolean
This general parameter must be set to "1" for function activation. - number: string
This service number from the init function that the customer would call. - (origin: string) ="LANDLINE"
Sets the network from which the caller would be calling. "LANDLINE" or "MOBILE" are the two options. - (caller :string)
Can contain the caller's number. This number is then directly returned from the status function. - tan :string if: mode = "DTMF"
The TAN in the "DTMF" mode. - durationpart: integer
Indicates how long the simulated call should last. Although a response is immediately sent for the query, the indicated call length will elapse until the call ends. Repeated query of the status function returns the status "CALL" and a rising value for durationpart. If a value for this parameter has been selected that is smaller than that for duration, after the simulated call is over the status "RECALL" will be returned. Otherwise duration and durationpart are the same and the returned status will be "COMPLETE". Response:
- handle :string(50)
The transaction ID, as from the init function. An overview of all parameters and responses is provided by the Quick Reference Chart.
return to the top
A typical transaction with the required web service interactions is outlined in the following. The example also demonstrates what happens when the customer interrupts the connection prematurely and is requested to call once again.
-
The customer decides to make a purchase and activates the partner's Call2Pay application. The application generates a list of available countries and asks the customer to make a selection from this list. For the most probable country a new payment transaction is initiated by the application.
http://{service-url}/?action=country&accesskey=0123abc
&project=demo&amount=100¤cy=EUR&ip=127.0.0.1
error=0
countrycount=3
country[0]=DE
country[1]=CH
country[2]=AT
ipcountry=DE
ipprovider=UNKNOWN
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=100¤cy=EUR&title=10 Coins&multicall=1
error=0
status=INIT
handle=1000abcdef
expire=2007-01-15 12:00:00
number=09005 000 111 22
numberinfo=2.00 euros/min from a German landline; charges may vary from a mobile network.
origin=BOTH
amount=100
currency=EUR
mode=DIRECT
tan=
duration=30
durationpart=0
split=0
paid=0
callcnt=0
The following information is displayed to the customer.
Please call the following number and wait 30 seconds
until the call is automatically hung up!
10 Tokens will then be credited to your account.
09005 000 111 22 *
* 2.00 euros/min from a German landline; charges may vary from a mobile network.
The total cost of the call is 1.00 euro.
Select your country: Germany | Switzerland | Austria
-
A cyclical query should be sent from the website to the application server (for example, every 5 seconds using a Java script). This query retrieves the status of the transaction and thus maintains the reservation.
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=INIT
expire=2007-01-15 12:00:05
caller=
duration=30
durationpart=0
split=0
paid=0
callcnt=0
As soon as the customer places a call, the function returns the following, for example:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=CALL
expire=2007-01-15 12:00:10
caller=03012345xxx
duration=30
durationpart=5
split=0
paid=0
callcnt=0
The cyclical query updates the website and displays the call's progress for the customer:
Your payment is being processed. Please stay on the line
for another 25 seconds
until the call is automatically hung up!
If the customer hangs up 10 seconds to early, status returns the following:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=RECALL
expire=2007-01-15 12:00:25
caller=03012345xxx
duration=30
durationpart=20
split=0
paid=0
callcnt=0
-
The application now requests new data from the web service:
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=100¤cy=EUR&title=10 Tokens&multicall=1
error=0
status=REINIT
handle=1000abcdef
expire=2007-01-15 12:00:25
number=09005 000 111 88
numberinfo=2.00 euros/min from a German landline; charges may vary from a mobile network.
origin=BOTH
amount=100
currency=EUR
mode=DIRECT
tan=
duration=30
durationpart=20
split=0
paid=0
callcnt=0
... and asks the customer to place the call again:
Unfortunately, you hung up the phone to early!
Please call again and stay on the line for 10 seconds,
until the call is automatically hung up!
09005 000 111 88 *
* 2.00 euros/min from a German landline; charges may vary from a mobile network.
The total cost of both calls is 1.00 euro.
The status function now returns the following:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=REINIT
expire=2007-01-15 12:00:25
caller=03012345xxx
duration=30
durationpart=20
split=0
paid=0
callcnt=0
... and at 5 second intervals once the customer places the call:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=CALL
expire=2007-01-15 12:00:30
caller=03012345xxx
duration=30
durationpart=25
split=0
paid=0
callcnt=0
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=COMPLETE
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=30
durationpart=30
split=0
paid=0
callcnt=0
-
The payment transaction is now complete, and the customer can make use of the service for which he or she has paid. For maintenance and support the info function can be used at any time in order to review the details of the transaction:
http://{service-url}/?action=info&accesskey=0123abc&handle=1000abcdef
error=0
expire=2007-01-15 12:00:35
project=demo
projectcampaign=
account=10010
webmastercampaign=
country=DE
number=09005 000 111 88
amount=100
currency=EUR
mode=DIRECT
tan=
caller=03012345xxx
duration=30
durationpart=20
title=10 Tokens
freeparam=
split=0
paid=0
callcnt=0
-
Now the prior example will be adapted to demonstate a transaction when the payment amount is 13.50 euros. The Multicall method is used. The interaction proceeds as follows:
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=1350¤cy=EUR&title=10 Tokens&multicall=1
error=0
status=INIT
handle=1000abcdef
expire=2007-01-15 12:00:00
number=09005 000 111 22
numberinfo=10.00 euros/call from a German landline; charges may vary from a mobile network.
origin=BOTH
amount=1350
currency=EUR
mode=DIRECT
tan=
duration=45
durationpart=0
split=1000
paid=0
callcnt=0
The following information is displayed to the customer.
Please call the following number and stay on the line
until the call is automatically hung up!
10 Tokens will then be credited to your account.
If you're calling from a German landline,
you'll be asked to pay with 2 phone calls. Your telephone bill will only be charged
after you have placed both calls to pay the total amount.
09005 000 111 22 *
* 10.00 euros from a German landline; charges may vary from a mobile network.
The total charge is 13.50 euros.
After a successfully completed call, the status query then returns the following:
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=REINIT
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=45
durationpart=0
origin=LANDLINE
freeparam=
split=350
paid=1000
callcnt=1
init must then be queried again. This must be repeated until all Multicalls have been successfully completed, see status.
http://{service-url}/?action=init&accesskey=0123abc
&project=demo&sessionid=aabbccddeeff&ip=127.0.0.1
&country=DE&amount=1350¤cy=EUR&title=10 Tokens&multicall=1
error=0
status=REINIT
handle=1000abcdef
expire=2007-01-15 12:10:00
number=09005 000 111 22
numberinfo=10.00 euros/call from a German landline; charges may vary from a mobile network.
origin=BOTH
amount=1350
currency=EUR
mode=DIRECT
tan=
duration=45
durationpart=0
split=350
paid=1000
callcnt=1
http://{service-url}/?action=status&accesskey=0123abc&handle=1000abcdef
error=0
status=COMPLETE
expire=2007-01-15 12:00:35
caller=03012345xxx
duration=45
durationpart=45
origin=LANDLINE
freeparam=
split=0
paid=1350
callcnt=2
A. Quick Reference Chart
Function: country
Table A.1. Parameters for country function
| Parameters |
Type |
Standard |
Description |
| accesskey |
string |
|
Access key |
| testmode |
boolean |
0 |
Activate test mode |
| project |
string |
|
Project name |
| amount |
integer |
Payment amount from project settings |
Payment amount |
| currency |
string(3) |
"EUR", if amount
|
Currency |
| ip |
string |
Empty |
Determine country from IP |
Table A.2. Parameters for country reponses
| Parameters |
Type |
Standard |
Description |
| error |
integer |
0 |
Error code |
| errormessage |
string |
If error <> 0 |
Error message |
| countrycount |
integer |
|
Number country[n]
|
| country[n] |
string(2) |
if countrycount > 0 |
Supported countries |
| ipcountry |
string(2) |
If ip <> "" |
Location of ISP based on IP |
| ipprovider |
string |
If ip <> "" |
ISP "UNKNOWN", "AOL" |
Function: init
Table A.3. Parameters for init function
| Parameters |
Type |
Standard |
Description |
| accesskey |
string |
|
Access key |
| testmode |
boolean |
0 |
Activate test mode |
| project |
string |
|
Project name |
| projectcampaign |
string |
None |
Campaign of project operator |
| account |
string |
Account of project operator |
Webmaster account |
| webmastercampaign |
string |
None |
Webmaster's campaign |
| sessionid |
string |
|
User session |
| ip |
string |
|
User IP |
| country |
string(2) |
|
User's country |
| language |
string(2) |
Country language |
Language of message heard by caller |
| amount |
integer |
Payment amount from project settings |
Payment amount |
| currency |
string(3) |
"EUR", if amount
|
Currency |
| title |
string |
Product from project settings |
Product for sale |
| freeparam |
string |
Empty |
Free parameters |
| multicall |
integer |
0 |
Allow Multicall |
Table A.4. Parameters for init reponses
| Parameters |
Type |
Standard |
Description |
| error |
integer |
0 |
Error code |
| errormessage |
string |
If error <> 0 |
Error message |
| status |
string |
|
Reservation status: "INIT", "REINIT", "CALL" |
| handle |
string(50) |
|
Reservation ID |
| expire |
datetimestring |
|
Expiration of the reservation |
| number |
string |
|
Call number |
| numberinfo |
string |
|
Legally required rate information |
| origin |
string |
|
Reachability of number: "MOBILE", "LANDLINE", "BOTH" |
| amount |
integer |
|
Payment amount |
| currency |
string(3) |
|
Currency |
| mode |
string |
|
Mode of user identification: "DIRECT", "DTMF" |
| tan |
string |
when mode = "DTMF" |
TAN input for call |
| duration |
integer |
|
Total call length in seconds |
| durationpart |
integer |
|
Elapsed call time in seconds |
| split |
integer |
|
Payment amount of current (Multi)call |
| paid |
integer |
|
Amount of completed (Multi)call |
| callcnt |
integer |
|
Number of completed (Multi)calls |
Function: status
Table A.5. Parameters for status function
| Parameters |
Type |
Standard |
Description |
| accesskey |
string |
|
Access key |
| testmode |
boolean |
0 |
Activate test mode |
| handle |
string(50) |
|
Reservation ID |
Table A.6. Parameters for status reponses
| Parameters |
Type |
Standard |
Description |
| error |
integer |
0 |
Error code |
| errormessage |
string |
If error <> 0 |
Error message |
| status |
string |
|
Reservation status: "INIT", "REINIT", "CALL", "RECALL", "COMPLETE" |
| expire |
datetimestring |
|
Expiration of the reservation |
| caller |
string |
If status >= "REINIT" and available |
Telephone number of the user |
| origin |
string |
Empty |
Network of the caller: "MOBILE", "LANDLINE" |
| duration |
integer |
|
Total call length in seconds |
| durationpart |
integer |
|
Elapsed call time in seconds |
| freeparam |
string |
Empty |
Free parameters |
| split |
integer |
|
Payment amount of current (Multi)call |
| paid |
integer |
|
Amount of completed (Multi)call |
| callcnt |
integer |
|
Number of completed (Multi)calls |
Function: info
Table A.7. Parameters for info function
| Parameters |
Type |
Standard |
Description |
| accesskey |
string |
|
Access key |
| testmode |
boolean |
0 |
Activate test mode |
| handle |
string(50) |
|
Reservation ID |
Table A.8. Parameters for info reponses
| Parameters |
Type |
Standard |
Description |
| error |
integer |
0 |
Error code |
| errormessage |
string |
If error <> 0 |
Error message |
| status |
string |
|
Reservation status: "INIT", "REINIT", "EXPIRED", "CALL", "RECALL", "FAILED", "COMPLETE" |
| expire |
datetimestring |
|
Expiration of the reservation |
| project |
string |
|
Project name |
| projectcampaign |
string |
Empty |
Campaign of project operator |
| account |
string |
|
Webmaster account |
| webmastercampaign |
string |
Empty |
Webmaster's campaign |
| country |
string(2) |
|
Country of the telepohone number |
| number |
string |
|
Call number |
| amount |
integer |
|
Payment amount |
| currency |
string(3) |
|
Currency |
| mode |
string |
|
Mode of user identification "DIRECT", "DTMF" |
| tan |
string |
If mode = "DTMF" |
TAN input for call |
| caller |
string |
If status >= "REINIT" and available |
Telephone number of the user |
| origin |
string |
Empty |
Network of the caller: "MOBILE", "LANDLINE" |
| duration |
integer |
|
Total call length in seconds |
| durationpart |
integer |
|
Elapsed call time in seconds |
| title |
string |
|
Product for sale |
| freeparam |
string |
Empty |
Free parameters |
| split |
integer |
|
Payment amount of current (Multi)call |
| paid |
integer |
|
Amount of completed (Multi)call |
| callcnt |
integer |
|
Number of completed (Multi)calls |
Function: testcall
Table A.9. Parameters for testcall function
| Parameters |
Type |
Standard |
Description |
| accesskey |
string |
|
Access key |
| testmode |
boolean |
|
Must be "1" |
| number |
string |
|
Call number |
| origin |
string |
"LANDLINE" |
Call network: "LANDLINE", "MOBILE" |
| caller |
string |
Empty |
Telephone number of the user |
| tan |
string |
If mode = "DTMF" |
TAN input for call |
| durationpart |
integer |
|
Number of seconds to be called |
Table A.10. Parameters for testcall reponses
| Parameters |
Type |
Standard |
Description |
| error |
integer |
0 |
Error code |
| errormessage |
string |
If error <> 0 |
Error message |
| handle |
string(50) |
|
Reservation ID |
return to the top
B. Error Codes
Table B.1. Errors caused by server (permanent)
| error |
Functions |
Cause |
Reaction |
| 1000 |
all |
Unknown error |
Information to micropayment support |
| 1001 |
all |
Error during database operation |
Information to micropayment support |
| 1002 |
all |
Failed initialization of service |
Information to micropayment support |
Table B.2. Errors caused by server (temporary)
| error |
Functions |
Cause |
Reaction |
| 2001 |
all |
Service temporarily unavailable (usually due to short-term maintenance work) |
Text displayed to user: "Please try again later" |
| 2002 |
init |
Reservation is temporarily not possible (usually the number pool has been exhausted) |
Text displayed to user: "Please try again later" |
Table B.3. Errors caused by client
| error |
Functions |
Cause |
Reaction |
| 3001 |
all |
Failed authorization (access key or IP of client is incorrect) |
Verification of project settings |
| 3002 |
all |
Function not supported or available |
Verification of documentation; the function may only be allowed in the test mode |
| 3003 |
all |
Parameter is in the wrong format or contains the wrong value (usually when required parameters are missing) |
Verification of documentation; input of all required parameters; input of correct values |
| 3004 |
all |
Error in project configuration |
Verification of project settings; errormessage returns more precise details |
| 3005 |
init |
Requested country is not available |
Text displayed to user: "Country is not supported" |
| 3006 |
init, country
|
Requested payment amount is not permitted |
Select another payment amount |
| 3007 |
init, country
|
Requested currency cannot be processed |
Input of currency in accordance with ISO 4217 |
| 3008 |
status, info
|
Handle is invalid |
Input of a valid handle, status only returns data for a limited time, use the info function
|
Table B.4. Errors caused by user
| error |
Functions |
Cause |
Reaction |
| 4001 |
testcall |
Call number or TAN not reserved or call is already underway |
Input of correct values; one-time call |
return to the top
|