Call2Pay API Event v2.0

1. Introduction

1.1. General

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:

  1. Selection of the country from which the customer would like to call, and, if applicable, selection of the desired rate.

  2. Displaying the reserved Call2Pay telephone number with pricing information required by law, and a waiting function until the required call duration is complete.

  3. 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:

  1. 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

  2. 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

2. Interface

2.1. General

2.1.1. Overview

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

return to the top

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.

return to the top

2.1.3. Error Codes

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

2.1.4. Service Protocols

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
2.1.4.2. Simple HTTP

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. Functions

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

2.3. Example

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.

  1. 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&currency=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&currency=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
    

  2. 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
    

  3. 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&currency=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
    

  4. 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
    
  5. 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&currency=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&currency=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
    
return to the top

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