Requests and responses

Our API Server application - the Directkit is accessible via Soap WebService (XML) or JSON-based WebService (JSON). This document describes the generic format of requests and responses for the Directkit :

  • The encoding of requests and responses is UTF-8
  • Your choice of Directkit URL decides the format of requests and responses (SOAP XML or JSON):
    • Soap WebService URL is https://.../directkitxml/service.asmx
    • Json WebService URL is https://.../directkitjson2/service.asmx

Any technology that supports HTTP (PHP, Python, nodejs, Ruby, Golang...) can communicate with our Directkit API. 

The directkitjson2 is often simpler to integrate and more network-efficient. So, it is recommended over directkitxml.

See also: Tutorials

For legacy customers

  • If your current Direckit URL is https://.../directkit/service.asmx You are using the legacy instance of directkit. You should migrate to the directkitxml which is mostly the same (or even better the directkitjson2)
  • If your current Direckit URL is https://.../directkitjson/service.asmx You are using the legacy instance of directkit. You should migrate to the directkitjson2 which is mostly the same.


Requests

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
 <soap12:Body>

<MethodName xmlns="Service_mb">

<wlPass>string</wlPass>
<wlLogin>string</wlLogin>
<language> string </language>
<version> string </version>
<walletIp> string </walletIp>
<walletUa>string </walletUa>
... 

</MethodName>

</soap12:Body>
</soap12:Envelope>

{

    "p":{   
        "wlPass":"string",
        "wlLogin":"string",
        "language":" string ",
        "version":" string ",
        "walletIp":" string ",
        "walletUa":"string"
        ...

    }

}

MethodName : name of the method in this API, i.e. "RegisterWallet"

All requests should contain:

Item

Description

Mandatory

Format

Example

wlLogin

Your WHITE BRAND login

Yes

[1 : 50] char

Pizza87

wlPass

Your access key given after the creation of your WHITE BRAND, you can change it in the backoffice.

Yes

[1 : 50] char

aizohdeh78

language

Response language

Yes

[2 : 3] char

fr : French (by default)

version

Used by legacy clients in old system which might crash if the directkit return newer fields.. We recommend to put a big version number in the request for eg "10.0" to always get the newest fields from the response of the latest directkit version.

Yes

[4] char

1.0 (by default)

walletIp

IP address of the final client

Please send the IP address of your client (the payer), not your server, to help us fight against fraud and reduce your Customer Care calls when we have a claim from a user. If you don't have it. Please use one of the IP public of the server which make the call or at least an IP public which belong to you (For eg IP of your website)

Yes

char

91.222.226.32

walletUa

User-agent of the final client

Please send the User-agent of the end-users browser. If you don't have it, you can put something which will help you identify the caller or the motivation of the call.

No

char

Mozilla/5.0 (Windows NT 6.1; WOW64) 


Responses

Each response is returned as a string:

<?xml version="1.0" encoding="utf-8"?>
<SomeResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="Service_mb_xml">
    <E>...</E> <!-- available only in case of error -->
    <Key>{Value}</Key>
</SomeResult>

{
    "d": {
        "__type": "WonderLib.SomeResult"

        "E": {..} /* available only in case of error */
        "Key": {value} /* result */
    } 

}

Json2 Request Reponse example

You can call DirectkitJson with PostMan on a whitelisted machine

  • In the header of your request, you need to specify the content-type : "Content-type: application/json; charset=utf-8"
  • Add the method name to the end of the Directkit URL, that is where you need to POST the data. Example if you wish to call RegisterWallet: https://.../directkitjson2/service.asmx/RegisterWallet



Service Description

A description for the WebService (WSDL) is available. If you want to use it, just add ?wsdl at the end of the Directkit URL. Eg: https://.../directkitxml/service.asmx?wsdl

  • The WSDL is human-readable, you could relies on it to know the exact input/output structure of a function service without consulting our documentation.
  • Most of object-oriented technologies (C #, Java ..) support the generation of all the structures of requests / responses based on this WSDL. 
    • The generation of these "artifacts" (or "stubs") might facilitate your development and it's optional.


Error Http Status 500

There are 2 possible causes:

1. (Most of time) the cause is the Bad request request format on client side. 

  • We often see that partners use the old PHP SDK to make request to the directkit legacyhttps://.../directkit/service.asmx 
    1. old PHP SDK is only compatible with the directkitxml https://.../directkitxml/service.asmx
    2. both the old PHP SDK and the directkit legacy have got only limited support, it won't be futher renovated.
  • We often see that partner request for the directkit json2: https://.../directkitjson2/service.asmx but "forgot" the "p" wrapper in the requests

2. This error might also coming from our side (rare) when the environment is down especially in case of sandbox, you can confirm it by running good request from Postman or the cURL command line. If there is doubt you can contact our support we will check.