Skip to content

Latest commit

 

History

History
432 lines (334 loc) · 12 KB

protocols.md

File metadata and controls

432 lines (334 loc) · 12 KB
Raw

Protocol details

The registry API protocol is composed of two major parts: voucher generation and payments. Both parts are based on 2 API methods.

Voucher creation request

Request from instrument to registry, generating a new voucher generation request.

POST /api/v1/voucher/create

Payload

{
    "SourceId": 1,
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Payload": "<see below>"
}
Property Type Description
SourceID integer Unique identifier of the source requesting new vouchers.
Nonce string Unique (per-source) string that ensures non-repetition.
Payload string JSON object encrypted with the registry’s public key.

The JSON object Payload has the following structure:

{
    "SourceId": 1,
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Password": "1234",
    "Vouchers": [
        {
            "Aim": "1",
            "Latitude": 12.34,
            "Longitude": 12.34,
            "Timestamp": "timestamp in ISO 8601 format",
            "Count": 1
        }
    ]
}
Property Type Description
SourceID integer Unique source identifier, must match that of container object.
Nonce string Non-repetition string, must match that of container object.
Password string User-supplied password for voucher generation confirmation. Between 4 and 8 numeric characters.
Vouchers string Array of voucher information.
Aim string URL identifying a common good aim within the WOM platform.
Latitude numeric
Longitude numeric
Timestamp string Time and date, UTC, ISO 8601 format.
Count numeric Optional. Indicates how many times the voucher template will be repeated. Defaults to 1.

Result

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the source's public key. Contents of the object are shown below:

{
    "RegistryUrl": "https://wom.social",
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8"
}
Property Type Description
RegistryUrl string URL, identifies the registry.
Nonce string Non-repetition string, must match that of request.
Otc string Unique one-time code identifying the voucher generation request.

Voucher creation verification

Request from instrument to registry, verifying a previous voucher generation request. This request is usually performed right after submitting a successful voucher generation request (see above).

POST /api/v1/voucher/verify

Payload

{
    "Payload": "<see below>"
}

The JSON object Payload is encrypted with the registry’s public key and has the following structure:

{
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8"
}
Property Type Description
Otc string Unique one-time code identifying the voucher generation request, previously generated by a voucher creation request.

Result

This method will return an empty response with HTTP status 200 to confirm verification.

Voucher redemption

Request from pocket to registry, completing the voucher generation request and returning instances of vouchers to the pocket, which can use them to process payments.

POST /api/v1/voucher/redeem

Payload

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the registry's public key. Contents of the object are shown below:

Property Type Description
Otc string Uniquely represents the voucher generation instance. Is a GUID in the current implementation.
Password string Short user-provided code that secures transmission of the Otc. 4 to 8 numeric characters.
SessionKey string 256-bit session key used to encrypt the response. Encoded in base64.

Result

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the session key specified in the request.

Note: encryption makes use of the 256-bit AES algorithm in CBC mode, with PKCS#7 padding. The first 128 bits of the payload make up the CBC Initial Vector. The rest of the payload is the actual encrypted data.

Contents of the decrypted JSON object have the following structure:

{
    "SourceId": 1,
    "SourceName": "Sample source",
    "Vouchers": [
        {
            "Id": 456,
            "Secret": "l2gLa87JhEVwF5KH8VkkPA==",
            "Aim": "11",
            "Latitude": 10.0,
            "Longitude": 12.3,
            "Timestamp": "2019-02-25T22:58:13Z"
        }
    ]
}

Each voucher object has the following properties:

Property Type Description
Id integer Unique voucher ID.
Secret string Sequence of random bytes (16 in current implementation), encoded in base64.
Aim string URL representing the voucher’s aim.
Latitude number
Longitude number
Timestamp string Time and date, UTC, ISO 8601 format.

Payment registration

Request from POS to registry, generating a new payment request.

POST /api/v1/payment/register

Payload

{
    "PosId": 1,
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Payload": "<see below>"
}
Property Type Description
PosId integer Unique identifier of the POS generating a new payment instance.
Nonce string Unique (per-source) string that ensures non-repetition.
Payload string JSON object encrypted with the registry’s public key.

The JSON object Payload has the following structure:

{
    "PosId": 1,
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Password": "1234",
    "Amount": 10,
    "SimpleFilter": {
        "Aim": "11",
        "Bounds": {
            "LeftTop": [ 45.0, -170.0 ],
            "RightBottom": [ 50.0, -160.0 ]
        },
        "MaxAge": 14
    },
    "PocketAckUrl": "pocket://confirmation-url",
    "PosAckUrl": "https://merchant.com/confirmation",
    "Persistent": false
}
Property Type Description
PosId integer Unique POS identifier, must match that of container object.
Nonce string Non-repetition string, must match that of container object.
Password string User-supplied password for voucher generation confirmation. Between 4 and 8 numeric characters.
Amount integer Amount of vouchers required for the payment.
SimpleFilter object Optional filter that vouchers must satisfy to be used for payment.
Aim string Code identifying a common good aim within the platform.
Bounds object Couple of coordinates identifying a square geographical region.
MaxAge integer Maximum age of vouchers, in days.
PocketAckUrl string Required. Confirmation URL that will be invoked by Pocket on payment success.
PosAckUrl string Optional. URL invoked via HTTP request by the Registry on payment success.
Persistent boolean Optional (defaults to false). Set to true in order to create persistent payments that can be performed multiple times.

Result

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the POS's public key. Contents of the object are shown below:

{
    "RegistryUrl": "https://wom.social",
    "Nonce": "91553f9f3d404a5399a7a7d651bb0ddd",
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8"
}
Property Type Description
RegistryUrl string URL, identifies the registry.
Nonce string Non-repetition string, must match that of request.
Otc string Unique one-time code identifying the payment request.

Payment verification

Request from POS to registry, verifying a previous payment request. This request is usually performed right after submitting a successful payment request (see above).

POST /api/v1/payment/verify

Payload

{
    "Payload": "<see below>"
}

The JSON object Payload is encrypted with the registry’s public key and has the following structure:

{
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8"
}
Property Type Description
Otc string Unique one-time code identifying the payment request, previously generated by a payment request.

Result

This method will return an empty response with HTTP status 200 to confirm verification.

Payment information

Request from pocket to registry, querying information about a payment.

POST /api/v1/payment/info

Payload

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the registry's public key. Contents of the decrypted JSON object have the following structure:

{
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8",
    "Password": "1234",
    "SessionKey": "cXVlc3RpcXVlc3RpcXVlc3RpcXVlc3RpcXVlc3RpMjI="
}
Property Type Description
Otc string Uniquely represents the payment instance. Is a GUID in the current implementation.
Password string Short user-provided code that secures transmission of the Otc. 4 to 8 numeric characters.
SessionKey string 256-bit session key used to encrypt the response. Encoded in base64.

Result

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the session key specified in the request.

Contents of the decrypted JSON object have the following structure:

{
    "PosId": 1,
    "PosName": "Sample POS",
    "Amount": 10,
    "SimpleFilter": {
        "Aim": "11",
        "Bounds": {
            "LeftTop": [ 45.0, -170.0 ],
            "RightBottom": [ 50.0, -160.0 ]
        },
        "MaxAge": 14
    },
    "Persistent": false
}
Property Type Description
PosId integer Unique ID of the POS that generated the payment.
Amount integer Amount of vouchers required to confirm the payment.
SimpleFilter object Filter that vouchers must satisfy in order to be accepted. May be null.
Aim string Code identifying a common good aim within the platform.
Bounds object Couple of coordinates identifying a square geographical region.
MaxAge integer Maximum age of vouchers, in days.
Persistent boolean Whether the payment instance is persistent or not.

Payment processing

Request from pocket to registry, performing a payment.

POST /api/v1/payment/confirm

Payload

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the registry's public key. Contents of the decrypted JSON object have the following structure:

{
    "Otc": "8b7abe3dda5f42e0b8235a819b0088b8",
    "Password": "1234",
    "SessionKey": "cXVlc3RpcXVlc3RpcXVlc3RpcXVlc3RpcXVlc3RpMjI=",
    "Vouchers": [
        {
            "Id": 456,
            "Secret": "l2gLa87JhEVwF5KH8VkkPA=="
        }
    ]
}
Property Type Description
Otc string Uniquely represents the payment instance. Is a GUID in the current implementation.
Password string Short user-provided code that secures transmission of the Otc. 4 to 8 numeric characters.
SessionKey string 256-bit session key used to encrypt the response. Encoded in base64.
Vouchers array Array of voucher objects.
Id integer Unique ID of the voucher.
Secret string Secret byte payload, must match the related voucher.

Result

{
    "Payload": "<see below>"
}

Payload is a JSON-encoded object, encrypted with the session key specified in the request.

Contents of the decrypted JSON object have the following structure:

{
    "AckUrl": "pocket://confirmation-url"
}
Property Type Description
AckUrl integer Confirmation URL that will be invoked by Pocket.