NAV
curl

About Coowry (v0.11.6)

   ______  
  / ____/__  ___ _      _________  __
 / /   / _ \/ _ \ | /| / / ___/ / / /
/ /___/ /_   _/ / |/ |/ / /  / /_/ /
\____/\___/\___/|__/|__/_/   \__, /
                            /____/

Coowry enables customers of mobile operators and merchants to send and request airtime in exchange for products and services. Coowry develops an exchange economy that builds a sustainable ecosystem for the digital society.

With Coowry anyone with a mobile phone can send and receive airtime, with no fees and without the need to provide any additional personal or financial information.

Totally free. No commissions and no hidden costs.

Microtransactions. You can exchange any ammount from cents up to $10.

Ready to use. All you need is a mobile phone.

Coowry can be used to transfer airtime to exchange digital or physical stuff. It can also be used by companies as a payment or a settlement method with their partners.

The name “Coowry” evokes the name of a seashell that was historically used as currency to exchange goods worldwide.

FTC

FTC is the essential concept of Coowry. FTC means Future Telecom Consumption and represents the airtime or mobile balance that you can use for communication services as well as transfer to other users in Coowry.

Trades and traders

A trade the essential object of Coowry. A trade represents a transfer of airtime. Two traders are involved in every trade: sender and receiver.

There are three kinds of traders

In addition to sender and receiver two pieces of information complete a trade:

Actions

There are three actions that result in a trade: sending airtime, requesting airtime and sending a bulk.

Channels

Coowry supports an increasing number of channels that enable traders to execute trades. Currently, the channels available are:

About this Documentation

This documentation is divided vertically into three sections: An index with the contents on the left, a description of the API and instructions to use it in the center, and code and examples on the right.

There is a cheatsheet to get you started on the basics. You should go through this first.

The sections Trades, Bulks and FTC contain a thorough description of these resources and go into detail on how to use them.

API Introduction

Coowry Core is RESTful

The Coowry Transactional Core is constructed as a RESTful service, and has been designed following these rules.

API Endpoint: https://api.coowry.com/v1

The API is resource oriented. Every resource offers a different view of the Coowry business data model. We rely on built-in HTTP features (authentication, verbs, etc.) that can be understood by off-the-shelf HTTP clients.

Request and Response Formats

         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment
          |   _____________________|__
         / \ /                        \
         urn:example:animal:ferret:nose

Source: http://tools.ietf.org/html/rfc3986

Authentication

Authentication is done via HTTP Basic Auth: Key and Secret.

All requests to the API must be done via HTTPS.

The Key used to authenticate is used by the system to expose just the pieces of information accesible by the key. Permissions shows which resources are available to each type of trader.

Timestamps and pagination

Timestamps in Coowry are progressed as Unix timestamps, i.e. number of seconds between a particular date and the Unix Epoch (January 1st, 1970 at UTC).

The Coowry API uses, for the moment, a non usual pagination method. Each request for a collection of resources can indicate two timestamps: from and to. The response will return all resources created between both timestamps.

From and to timestamps are optional. If to is not indicated, then now is used. If from is not indicated, then the first second of the previous month is used. Thus if neither from nor to are indicated, resources created in the last two months are returned.

The response is limited to 1000 resources and includes four keys in the JSON hash: from', to, total and list. List is an array of resources, total is the number of returned resources, to is the to timestamp in the request.

If the limit is not reached, from' is equal to from in the request. Otherwise, from' is the timestamp that indicates the creation timestamp of the first resource.

Versioning

Coowry uses Semantic Versioning in all its products. Versions follow the format X.Y.Z (X for major number, Y for minor number, and Z, for patch number). Bug fixes increment the patch version, backwards compatible changes increment the minor version, and backwards incompatible API changes increment the major version.

Major version is reflected in the API end point https://preapi.coowry.com/vX that behaves as a resource that indicates the whole version number.

{"description":"Coowry Transactional Core","version":"0.10.10"}

At this moment the major version operating is v1 and the current major version number can be found at https://api.coowry.com/v1.

Metadata

Some resources also provide reference, description and/or concept parameters that can be used to store metadata strings.

Furthermore, most updatable Coowry resources are ready to support a user-specified metadata parameter that can be used to attach key-value data (eg. JSON) at your convenience.

Cheatsheet

This section contains a step by step guide on how to perform the most common tasks when using Coowry: charging and refunding a customer, checking your FTC, making settlements, setting and using callbacks and forcing the resend of authorization SMS.

This is a cheatsheet, and is intented as a quick reference guide. A thorough read of the complete documentation is recommended.

Charging a Customer

Example: Charging a customer

Definition: POST https://api.coowry.com/v1/trades

EXAMPLE REQUEST
$ curl -u foo:bar -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://api.coowry.com/v1/trades" -d "sender=+628186445653" -d "receiver=foo" -d "concept=Subscription renewal" -d "value=500000" -d "currency=IDR" -d "reference=ref:193716" 

EXAMPLE RESPONSE (if customer has enough balance)

HTTP/1.1 200 OK
{
        "status": "created",
        "trid": "tr-la2js1mlrkrk",
        "sort": "p2b",
        "value": 500000,
        "currency": "IDR",
        "sender": "51011128471628312",
        "sender_name": "+628186445653",
        "sender_net": "51011",
        "sender_net_name": "XL",
        "receiver": "foo",
        "receiver_name": "Company Name",
        "receiver_net": "51011",
        "receiver_net_name": "XL",
        .
        .
        .
        "created": 1440231774,
        "orderer": "foo",
}

EXAMPLE RESPONSE (if customer does not have enough balance)

HTTP/1.1 412 Precondition Failed
{
  "status": 412,
  "type": "sender_not_enough_balance",
  "description": "Sender does not have enough balance",
  "arguments": {"excess_value": { "value": 5000, "currency": "IDR"}}
}

To charge a customer you must create a trade requesting airtime from him. This is equivalent to making a POST request to /trades. The following fields must be specified in the body of the request:

The body of the request must be encoded either in application/json or application/x-www-form-urlenconded. The Content-Type header should be set accordingly.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

If the customer has enough balance, the trade will be created. You must then wait for the customer to authorize it. Once this happens the transfer of airtime will be executed.

The customer has up to 24 hours to authorize the transaction. After that the trade will fail.

Changes in the status of the trade (when it is authorized or fails) will be notified through a callback to the URI you have specified (more info on how to do this here).

Refunding a Customer

Example: Refunding a customer

Definition: POST https://api.coowry.com/v1/trades

EXAMPLE REQUEST
$ curl -u foo:bar -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://api.coowry.com/v1/trades" -d "sender=foo" -d "receiver=+628186445653" -d "concept=Refund" -d "value=500000" -d "currency=IDR" -d "reference=ref:12214" 

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
  "status": "authorized",
  "trid": "tr-la2jsj3rkrk",
  "sort": "b2p",
  "value": 500000,
  "currency": "IDR",
  "sender": "foo",
  "sender_name": "Company Name",
  "sender_net": "51011",
  "sender_net_name": "XL",
  "receiver": "51011128471628312",
  "receiver_name": "+628186445653",
  "receiver_net": "51011",
  "receiver_net_name": "XL",
  .
  .
  .
  "created": 14402123774,
  "orderer": "foo",
}

To refund a customer you must create a trade sending airtime to him. As before, this means making a POST request to /trades. The following fields must be specified in the body of the request:

The body of the request must be encoded either in application/json or application/x-www-form-urlenconded. The Content-Type header should be set accordingly.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

If all the parameters are valid and you identified yourself correctly, the trade will be authorized automatically, and the transfer of airtime will be executed.

Checking your FTC

Example: Checking your FTC

Definition: GET https://api.coowry.com/v1/ftc

EXAMPLE REQUEST
$ curl -u foo:bar -v -X GET "https://api.coowry.com/v1/ftc"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
  "length": 31,
  "ftc": [
    {
      "ag": "foo",
      "net": "51003",
      "net_name": "StarOne",
      "ag_name": "Company Name",
      "currency": "IDR",
      "balance": 250000000,
      "credit": 150000000,
      "available": 400000000
    },
    {
      "ag": "foo",
      "net": "51011",
      "net_name": "XL",
      "ag_name": "Company Name",
      "currency": "IDR",
      "balance": 15500000,
      "credit": 0,
      "available": 15500000
    },
    .
    .
    .
    {
      "ag": "foo",
      "net": "52506",
      "net_name": "StarHub",
      "ag_name": "Company Name",
      "currency": "IDR",
      "balance": 55100000,
      "credit": 0,
      "available": 55100000
    }
  ]
}

This is a simple one, just make a GET request to /ftc and your current FTC in all the networks will be returned.

No additional parameters need to be supplied.

As always, authorization must be done via HTTP Basic Auth, providing your API key and secret.

The response contains your balance and credit in each network. The most important fields are,

For more info, have a look at FTC.

Making settlements: Ordering a bulk

Example: Ordering a bulk

Definition: POST https://api.coowry.com/v1/bulks

EXAMPLE REQUEST
$ curl -u foo:bar -X POST "https://api.coowry.com/v1/bulks" -d "authorizer=+628196616987" -d "csv=@bulk.csv" -d "currency=IDR" -d "reference=ref:12345"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
  "no_rows": 34,
  "status": "created",
  "bkid": "bk-ue03ua8qvt5b",
  "sender": "foo",
  "authorizer": "+34616616987",
  "created": 1440968954,
  "ip_create": "undefined", //Hashed
  "authorized": null,
  "ip_authorize": null,
  "auth_token": "$2a$04$a227g"
  "auth_tries": 0,
  "currency": "IDR",
  .
  .
  .
  "reference": "ref:12345"
}


Example: Authorizing a bulk

Definition: POST https://api.coowry.com/v1/bulks/:bkid/authorization

EXAMPLE REQUEST
$ curl -u foo:bar -X POST "https://api.coowry.com/v1/bulks/bk-ue03ua8qvt5b/authorization" -d "token=1234"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
  "no_rows": 34,
  "status": "authorized",
  "bkid": "bk-ue03ua8qvt5b",
  "sender": "foo",
  "authorizer": "+34616616987",
  "created": 1440968954,
  "ip_create": "undefined", //Hashed
  "authorized": null,
  "ip_authorize": null,
  "auth_token": "$2a$04$a227g"
  "auth_tries": 1,
  "currency": "IDR",
  .
  .
  .
  "reference": "ref:12345"
}

Bulks are used to execute a large number of trades in one go. They are used to refund customers or make settlements at a massive scale.

This process has two stages, creating the bulk and authorizing it:

Creating the bulk

You must specify the trades in CSV format (can be a separate file) that is sent in the body of the request. The CSV format is specified here.

The bulk is ordered by making a POST request to /bulks. The following parameters must be specified in the request body:

The body of the request must be encoded either in application/json or application/x-www-form-urlenconded. The Content-Type header should be set accordingly.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

If all the parameters are correct, you will receive a JSON response containing details on the created bulk. At this point an SMS will be sent to the MSISDN specified in the authorizer field, with a token to authorize the bulk.

Authorizing the bulk

Once the bulk is created the authorizer will receive a token to authorize the bulk. This is done as a two-stage authentication for increased security.

The authorization token expires after 5 minutes.

To authorize the bulk, you must create a POST request to /bulks/:bkid/authorization, where :bkid is the bulk id, returned in the body of the request when the bulk was created.

The request body must contain the following field:

Authorization and headers must be set as always.

If the token is correct, the bulk will be authorized and the trades executed. Remember, authorizing the bulk does not guarantee that the trades will be succesful.

Using callbacks

Example: Testing your callback

Definition: POST https://api.coowry.com/agents/:agid/callbacks/test

EXAMPLE REQUEST
$ curl -u foo:bar -X POST https://api.coowry.com/v1/agents/foo/callbacks/test -d ""

EXAMPLE RESPONSE

HTTP/1.1 204 OK

(No body)

You will receive the following request at your callback URI

HTTP/1.1 POST

{
  "signature":"4fe073735265ba7195b38e8104318ae712525009",
  "payload": {
               "status":"authorized","trid":"tr-testtrade123",
               "sort":"p2b",
               "sender":"510010123456789",
               "sender_name":"+62123456789",
               "sender_net":"51001",
               "sender_net_name":"Indosat",
               "receiver":"ag-Whatsap",
               "receiver_name":"Whatsapp",
               "receiver_net":"51001",
               "receiver_net_name":"Indosat",
               "value":2,
               "currency":"USD",
               "sender_net_cer":1.0,
               "sender_currency":"USD",
               "receiver_net_cer":1.0,
               "receiver_currency":"USD",
               "concept":"Test trade for callbacks",
               "created":1462790381,
               "orderer":"ag-Whatsap",
               "failed":null,
               "failure":null
             }
}

The Coowry Core will make callbacks to an URI of your choice when a trade you have ordered changes status. This is specially convenient when dealing with the asynchronous events that affect a trade, such as a user authorizing a purchase via SMS.

When a trade is authorized or fails, a POST request will be made to the URI that you have specified, informing you of the event. The body of this request is a JSON object with two fields:

Callback secret and signature

A new secret is generated every time you set a callback URI. The field signature is calculated by

Make sure you append the secret to the JSON text inside payload exactly as it was returned by the API (watch out for tools that might sort fields alphabetically).

For example, the signature for the callback on the left was calculated by running a SHA1 digest over the following string:

{"status":"authorized","trid":"tr-testtrade123","sort":"p2b","sender":"510010123456789","sender_name":"+62123456789","sender_net":"51001","sender_net_name":"Indosat","receiver":"ag-Whatsap","receiver_name":"Whatsapp","receiver_net":"51001","receiver_net_name":"Indosat","value":2,"currency":"USD","sender_net_cer":1.0,"sender_currency":"USD","receiver_net_cer":1.0,"receiver_currency":"USD","concept":"Test trade for callbacks","created":1462790381,"orderer":"ag-Whatsap","failed":null,"failure":null}av56cxsa1fyrbtc5

where av56cxsa1fyrbtc5 is the callback secret.

Testing your callback

Once you set a new callback, you can test it by making a POST request to /agents/foo/callbacks/test, where foo is your agent API Key. The body must be defined but left empty.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

This will trigger a callback to the URI that you have defined, with a dummy trade inside payload.

Setting your callback URI

Example: Setting your callback URI

Definition: POST https://api.coowry.com/agents/:agid/callbacks

EXAMPLE REQUEST
$ curl -u foo:bar -X POST https://api.coowry.com/v1/agents/foo/callbacks -d "callback_uri=https://mycompany.com/callbacks"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
  "callback_uri": "https://mycompany.com/callbacks",
  "callback_secret": "mwwzx6cuu5hjjpiv"
}

To set or change your callback URI, you must make a POST request to /agents/foo/callbacks, where foo is your agent API Key.

Only one parameter must be encoded in the request body:

The body of the request must be encoded either in application/json or application/x-www-form-urlenconded. The Content-Type header should be set accordingly.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

The Coowry API will return a JSON object with two fields:

You can renew the secret at any time by repeating the previous request.

Resending an authorization SMS

Example: Resend authorization SMS

Definition: POST https://api.coowry.com/trades/:trid/tokens

EXAMPLE REQUEST
$ curl -u foo:bar -X POST https://api.coowry.com/trades/:trid/tokens -d ""

EXAMPLE RESPONSE (Everything OK)

HTTP/1.1 204 OK

(No body)

EXAMPLE RESPONSE (Reached the limit of resends)

HTTP/1.1 412 Precondition Failed

{"status":412,"type":"too_many_renewals","description":"The token for this trade has been renewed too many times","arguments":{"max":3}}

EXAMPLE RESPONSE (Trade failed or has already been authorized)

HTTP/1.1 412 Precondition Failed

{"status":412,"type":"wrong_status","description":"Trade is in the wrong status","arguments":{"status":"authorized"}}

You can force the resend of an authorization SMS, which contains the token to authorize a trade. This is useful in cases when the SMS is not delivered or the user can’t find it.

To force the resend, make a POST request to /trades/:trid/tokens, where :trid is the ID of the trade you want to authorize. The body must be defined but left empty.

Authorization must be done via HTTP Basic Auth, providing your API key and secret.

This will renew the token assigned to the trade and send an SMS to the sender of the trade (or the authorizer if the sender is an agent). You can repeat this process a maximum of 3 times for a single trade.

Trades

Trades are the fundamental object in the Coowry API: they represent airtime transactions. Therefore, creating a trade is equivalent to requesting an airtime transaction.

Trade Status

Throughout their lifecycle, trades can be in three different states : created, authorized, failed.

Trade Authorization

Authorization of a trade is required for the transfer of airtime to be executed.

It is done by the sender of the trade. In some cases, like a purchase, the receiving agent can also authorize the trade if it has the authorization token.

Depending on who the sender is, authorization can be done in several ways, or might not be necessary at all.

Once a trade is authorized, both sides are informed and airtime is transferred from the sender to the receiver.

The Trade Object

Example Object

{
    "authorized": 1443282197,
    "authorizer": null,
    "bkid": null,
    "concept": "Blogger Liquidation",
    "created": 1443282197,
    "currency": "USD",
    "failed": null,
    "failure": null,
    "orderer": "ag-aB819bd",
    "receiver": "214058159557860",
    "receiver_currency": "EUR",
    "receiver_msisdn": "+34722730741",
    "receiver_name": "+34722730741",
    "receiver_net": "21405",
    "receiver_net_cer": 0.8950948800572861,
    "receiver_net_name": "TME",
    "reference": "Internal orderer reference",
    "sender": "ag-aB819bd",
    "sender_currency": "EUR",
    "sender_msisdn": null,
    "sender_name": "Coowry Ltd.",
    "sender_net": "21405",
    "sender_net_cer": 0.8950948800572861,
    "sender_net_name": "TME",
    "sort": "b2p",
    "status": "authorized",
    "trid": "tr-hgjmq23ieedp",
    "value": 448
}

Due to the complexity of the process involved in executing a transaction, the trade object is also one of the most extensive.

Attributes

trades/

Container for all the trades.

Definition: GET https://api.coowry.com/v1/trades

EXAMPLE REQUEST
$ curl -u foo:bar -X GET "https://api.coowry.com/v1/trades" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "from": 1412162782,
    "length": 204,
    "to": 1443698782,
    "trades": [
        {
            "concept": "Blogger Liquidation",
            "created": 1412168300,
            "currency": "USD",
            "failed": null,
            "failure": null,
            "orderer": "ag-aB819bd",
            "receiver": "250996044720540",
            "receiver_currency": "RUB",
            "receiver_name": "+790310033",
            "receiver_net": "25099",
            "receiver_net_cer": 65.4305,
            "receiver_net_name": "VimpelCom",
            "sender": "ag-Coowry_",
            "sender_currency": "RUB",
            "sender_name": "Coowry Ltd.",
            "sender_net": "25099",
            "sender_net_cer": 65.4305,
            "sender_net_name": "VimpelCom",
            "sort": "b2p",
            "status": "authorized",
            "trid": "tr-sd1a7nhu3rvo",
            "value": 666
        },
        ...

    ]
}

Definition: POST https://api.coowry.com/v1/trades

EXAMPLE REQUEST
$ curl -u foo:bar -X POST "https://api.coowry.com/v1/trades" -d "sender=34656445653" -d "receiver=34622485496" -d "concept=Gift" -d "value=200" -d "currency=USD"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "authorized": null,
    "authorizer": "214040656445653",
    "bkid": null,
    "concept": "Gift",
    "created": 1443699156,
    "currency": "USD",
    "failed": null,
    "failure": null,
    "orderer": "214040656445653",
    "receiver": "214040622485496",
    "receiver_currency": "EUR",
    "receiver_imsi": "214040622485496",
    "receiver_msisdn": "+34622485496",
    "receiver_name": "+34622485496",
    "receiver_net": "21404",
    "receiver_net_cer": 0.8963786303334529,
    "receiver_net_name": "Yoigo",
    "reference": null,
    "sender": "214040656445653",
    "sender_currency": "EUR",
    "sender_imsi": "214040656445653",
    "sender_msisdn": "+34656445653",
    "sender_name": "+34656445653",
    "sender_net": "21404",
    "sender_net_cer": 0.8963786303334529,
    "sender_net_name": "Yoigo",
    "sort": "p2p",
    "status": "created",
    "trid": "tr-c05hseuif5lg",
    "value": 200
}

GET

Returns all the trades created in a period of time.

Request

GET requests to this resource can provide the following arguments,

Response

The response is a list of trades sorted by creation date, limited to one year, and limited to 100 trades (this number could change). The JSON object returned has the following properties:

POST

Creates a new trade.

Request

POST requests to this resource must provide the following arguments,

Response

The response is a JSON object representing the new trade.

trades/:trid

Trade with unique identifier :trid.

Definition: GET https://api.coowry.com/v1/trades/:trid

EXAMPLE REQUEST
$ curl -u foo:bar -X GET "https://api.coowry.com/v1/trades/tr-c05hseuif5lg" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "authorized": null,
    "authorizer": "214040656445653",
    ...
    "sort": "p2p",
    "status": "created",
    "trid": "tr-c05hseuif5lg",
    "value": 200
}

GET

Returns the trade with the given identifier.

Request

The request has no arguments.

Response

The response is a JSON object representing the trade. As of right now all of the trade’s properties are displayed.

trades/:trid/authorization

Represents the authorization of the trade with identifier :trid.

Definition: POST https://api.coowry.com/v1/trades/:trid

EXAMPLE REQUEST
$ curl -v -X POST "https://api.coowry.com/v1/trades/tr-la2js1mlrkrk/authorization" -d "auth_token=0283" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 204 No Content

POST

Authorizes the trade with identifier :trid.

Request

The request must provide an authorization token as its only argument,

Response

The response is a JSON object representing the trade. As of right now all of the trade’s properties are displayed.

Bulks

Requesting a Bulk transaction allows you to send thousands of trades with a single API request. This action is only available for merchants (agents).

For the trades in the bulk to be executed, only the Bulk needs to be authorized (instead of every single trade).

The trades to be executed are specified through a CSV file, sent to the API in the body of the request. The format of this file is specified here.

The Bulk Object


EXAMPLE OBJECT
{
    "authorized": 1421103771,
    "authorizer": "+34616616987",
    "bkid": "bk-snimwp3b",
    "completed": null,
    "created": 1421099281,
    "csv": [
        {
            "concept": "Massive liquidation (should fail)",
            "currency": "USD",
            "failure": "unidentified",
            "receiver": "+34123456789",
            "reference": "Internal order reference",
            "trid": null,
            "value": 42
        },
        ...
    ],
    "failed": null,
    "failure": null,
    "reference": "Some internal orderer reference",
    "sender": "ag-rPpL3OZ",
    "status": "authorized"
}

CSV Format

Example bulk CSV

34629086701,1.34,EUR,Monthly settlement,Ref:136183612
34691363380,12,EUR,Publicity cash-out,pb-asd12311
34123456789,1.12,EUR,For phone bill,12384611
.
.
.

The trades of a Bulk are specified in Comma-separated values (CSV) format (can be in a separate file) which is sent in the body of the request to the API. It must have the following columns (in this order) for each row, with no spaces between the commas (“,”):

Attribute csv of the bulk object represents the CSV in JSON:

bulks/

Container for all the bulks.

Definition:  GET https://api.coowry.com/v1/bulks

EXAMPLE REQUEST
curl -u foo:bar -v -X GET "https://api.coowry.com/v1/bulks" | python -mjson.tool

EAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "bulks": [
        {
            "authorized": null,
            ...
            "sender": "ag-rPpL3OZ",
            "status": "created"
        },
        ...
    ],
    "length": 4
}

Definition: POST https://api.coowry.com/v1/bulks

EXAMPLE REQUEST
$ curl -u foo:bar -X POST "https://api.coowry.com/v1/bulks" --form authorizer=34616616987 --form csv=@bulk.csv --form test=true --form currency=EUR | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "authorized": null,
    ...
    "sender": "ag-rPpL3OZ",
    "status": "created"
}

GET

Returns all the bulks in the database, if the requester is Coowry. If the requester is an agent, returns only those that belong to it.

Request

The requester must be identified as Coowry or an agent using HTTP Basic Authentication.

This request has no parameters.

Response

The response is a list of bulks. The JSON object has the following properties,

POST

Creates a new bulk.

Request

The requester must be identified as Coowry or an agent using HTTP Basic Authentication.

The request must present the following arguments,

Response

The response is a JSON object representing the new bulk.

bulks/:bkid

Bulk with unique identifier :bkid.

Definition: GET https://api.coowry.com/v1/bulks/:bkid

EXAMPLE REQUEST
$ curl -u foo:bar -X GET "https://api.coowry.com/v1/bulks/bk-snimwp3b" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "authorized": 1421103771,
    "authorizer": "+34616616987",
    "bkid": "bk-snimwp3b",
    "completed": null,
    "created": 1421099281,
    "csv": [
               {
                  "receiver": 34629086701
                  "value": 500
                  "concept": "Developer Payment Nov-14"
                  "reference": "Developer Ref_50453445"
                  "trid": "ihtvrev366epe45o"
                  "failure": null
               },
          ...
          ],
    "failed": null,
    "failure": null,
    "reference": null,
    "sender": "ag-rPpL3OZ",
    "status": "authorized"
}

GET

Returns the bulk with the given :bkid.

Request

This request has no parameters.

Response

A JSON object representing the requested bulk.

bulks/:bkid/authorization

Authorizes the bulk with identifier :bkid.

Definition: POST https://api.coowry.com/v1/bulks/:bkid/authorization

EXAMPLE REQUEST
$ curl -u foo:bar -X POST "https://api.coowry.com/v1/bulks/bk-snimwp3b/authorization" -d "token=5855" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "authorized": 1421102833,
    ...
    "reference": null,
    "sender": "ag-rPpL3OZ",
    "status": true
}

POST

Authorizes the bulk with identifier :bkid.

Request

The request must provide an authentication token as it’s only argument:

Process

Trades are initialized as follows:

Response

A JSON object representing the authorized bulk.

bulks/:bkid/trades

Container for all the trades of the bulk with identifier :bkid.

Definition: GET https://api.coowry.com/v1/bulks/:bkid/trades

EXAMPLE REQUEST
$ curl -u foo:bar -X GET "https://api.coowry.com/v1/bulks/bk-snimwp3b/trades" | python -mjson.tool

EXAMPLE RESPONSE

HTTP/1.1 200 OK
[
    {
         "concept": "Developer Payment Nov-14",
         "created": "1417629699",
         "currency": "EUR",
         "receiver": "214040109834392",
         "receiver_name": "+34656445653",
         "receiver_net": "21404",
         "receiver_net_name": "Yoigo",
         "sender": "ag-rPpL3OZ",
         "sender_name": "TheGameStore",
         "sender_net": "21404",
         "sender_net_name": "Yoigo",
         "status": "authorized",
         "trid": "ihtvrev366epe45o",
         "value": 500
    }
....
]

GET

Retrieves all the trades of the bulk with identifier :bkid.

Request

This request has no parameters.

Response

A JSON object representing an array of trades. Each trade is a JSON object with the following set of trade properties:

FTC

Container for the balances of people and agents networks. FTC stands for Future Telecom Consumption.

FTC object

SIM BALANCE

{
  "available": 6337,
  "balance": 3837,
  "credit": 2500,
  "currency": "EUR",
  "net": "21404",
  "net_name": "Yoigo",
  "simid": "214040656445653"
}

AGENT BALANCE

{
  "ag": "ag-Coowry_",
  "ag_name": "Coowry Ltd.",
  "available": 895095,
  "balance": 0,
  "credit": 895095,
  "currency": "EUR",
  "net": "21421",
  "net_name": "Jazztel"
}

The object that represents the balance of an entity depends on the entity itself.

/ftc

Definition: GET https://api.coowry.com/v1/ftc

EXAMPLE REQUEST
$ curl -u foo:bar -v -X GET "https://api.coowry.com/v1/ftc"

EXAMPLE RESPONSE

HTTP/1.1 200 OK
{
    "ftcs": [
        {
            "available": 6337,
            "balance": 3837,
            "credit": 2500,
            "currency": "EUR",
            "net": "21404",
            "net_name": "Yoigo",
            "simid": "214040656445653"
        }
    ],
    "length": 1
}

GET Returns the balance of the requesting entity. Results vary depending on the requesting entity:

Errors

HTTP STATUS CODE SUMMARY
200 OK                    The request was properly processed.
204 No Content            The server has fulfilled the request 
                          but does not return an entity-body.
400 Bad Request           Missing or non valid parameter.
401 Unauthorized          Non valid credentials.
403 Forbidden             The server understood the request, but 
                          is refusing to fulfill it.
404 Not Found             The requested resource doesn't exist.
405 Method Not Allowed    The specified method is not allowed on
                          this resource.
409 Conflict              The request could not be completed due 
                          to a conflict with the current state of 
                          the resource. 
412 Precondition Failed   The precondition given in one or more 
                          of the request-header fields evaluated 
                          to false when tested on the server.
500 Server error          The request failed because of problems 
                          within the Coowry servers.
ERROR TYPES
already_exists
The given phone number already exists in the system

forbidden
The request you made is not allowed. Providing credentials won't help

malformed_request
The request contains syntax errors in it's body

method_not_allowed
That method is not allowed on this resource

net_not_member
The given number was identified but it's network does not operate with Coowry

not_authorized
Not Authorized (401). Please provide authentication credentials

not_billed
Could not charge the owner of a sim

not_captured
Could not top-up the owner of a sim

not_found
Resource not found (404)

not_unique_agent
An agent with the given parameters already exists

not_unique_net
A network with the given parameters already exists

not_unique_sim
A sim with the given parameters already exists

unidentified
Could not identify the given phone number

receiver_blacklist
Receiver is blacklisted and cannot operate

receiver_net_not_member
Receiver identified but his network does not operate with Coowry

receiver_unidentified
Receiver could not be identified

sender_blacklist
Sender is blacklisted and cannot operate

sender_not_enough_balance
Sender does not have enough balance to perform the transaction

sender_net_not_member
Sender was identified but his network does not operate with Coowry

sender_unidentified
Sender could not be identified

too_many_auth_attempts
The limit of authorization attempts for a trade of bulk has been reached

too_many_requests
Receiver has too many unauthorized airtime requests

trade_not_allowed
The trade you are trying to perform is not allowed

tr_not_found
Trade not found

unsupported_media_type
The format of the request's body is not supported

value_not_valid
The value of the trade is not valid

wrong_csv
The bulk's CSV file contains errors

wrong_status
The trade is in the wrong status (and could not be authorized)

wrong_bk_status
The bulk is in the wrong status (and could not be authorized)

wrong_token
The entered token is wrong

Coowry uses standard HTTP status codes to communicate the result of each request.

Further details about HTTP Status Codes can be found here.

Like any other request response, error responses are JSON objects. They present the following attributes:

Example error responses

EXAMPLE 1
{
  "status":400,
  "type":"value_not_valid",
  "description":"The value of the transaction is not valid",
  "arguments":{
                "currency":"EUR",
                "min_value":1,
                "max_value":889
              }
}
EXAMPLE 2
{
  "status":412,
  "type":"receiver_unidentified",
  "description":"Receiver not identified",
  "arguments":{}
}