Skip to content

Create a transaction

Overview

POST /api/v2/transactions/

This endpoint is used to enact purchases. Currently only hugggs can be purchased, either singly or in bulk, but this endpoint will later support all other available purchase types.

The API will also handle any follow on work that is required as part of a purchase, such as charging a card or shared wallet, and sending out notification texts and pushes.

Request

Note that the access token provided to this request must be for a user that has access to the specified payment method.

Data Parameters

Key Value Description
payment object Specifies the payment method for this transaction; field details follow.
payment.method string Must be card. Support will later be added for alternative payment methods.
payment.reference string The stripe card id.
purchase object Specifies the item(s) to be purchased; field details follow.
purchase.type string Must be huggg; support will later be added for alternative products.
purchase.reference string The id of the product to be purchased.
purchase.receivers (optional) Array An array of objects identifying the recipients of the purchased huggg(s).
purchase.message (optional) string If provided, this specifies the message displayed to the recipient when notified of / viewing their huggg.

purchase.receivers, if provided, is an array of objects of this form:

Key Value Description
phone_number (optional) string The recipient's mobile number.
user_id (optional) string The user's id.

Only one of phone_number or user_id should be provided for each item in the array. If a user_id is provided, and that user is not found in the system, the request will fail.

If purchase.receivers is not provided, a single huggg is generated with no assigned receiver, to be shared by Url.

Embedded Entities

The endpoint supports embedding related entities - for a detailed overview of how this works, please read [API Overview][overview].

Hugggs are available as embedded entities (which is useful when buying individual hugggs) but, when buying multiple hugggs, embedding does not allow for pagination of results. In this case, the endpoint [/transactions/{id}/hugggs] can be used to retrieve a paginated list of the purchased hugggs.

Relation Entity Description
hugggs.message Message An entity containing the message attached to a huggg
hugggs.voucher Voucher Sometimes hugggs have a voucher associated with them for redemption
hugggs.voucher.segment ProductSegment Details about the generic group the huggg's voucher is part of
hugggs.purchase [Product][product] The item that this huggg is for
hugggs.purchase.brand [Brand][brand] The brand associated with this huggg's purchase
hugggs.purchase.segments ProductSegment Any generic groupings associated with the huggg's purchase
hugggs.purchase.brand.stores [Store][store] All locations served by the the huggg's purchase's brand
hugggs.purchase.brand.integration Integration Details about the huggg's purchase's brand's main integration method with huggg

Examples

Send hugggs to four phone numbers

POST /api/v2/transactions

{
    "payment": {
        "method": "card",
        "reference": "stripe_id_for_card"
    },
    "purchase": {
        "type": "huggg",
        "reference": "a_product_id",
        "message": "Thanks for all your help!",
        "receivers": [
            {
                "phone_number": "+077777111111"
            },{
                "phone_number": "+077777222222"
            },{
                "phone_number": "+077777333333"
            },{
                "phone_number": "+077777444444"
            }
        ]
    }
}

Send a single huggg to a user and include the huggg and its redemption locations in the response

POST /api/v2/transactions?embed[]=hugggs.purchase.brand.stores

{
    "payment": {
        "method": "card",
        "reference": "stripe_id_for_card"
    },
    "purchase": {
        "type": "huggg",
        "reference": "a_product_id",
        "message": "Here's a huggg for you!",
        "receivers": [
            {
                "user_id": "a_user_id"
            }
        ]
    }
}

Response

The successful response returns the newly created Transaction entity, plus any embedded entities that were requested.

HTTP/1.1 201 created

{
    "data": {
        "id": "transaction-id",
        "retail": "transaction-cost",
        "created_at": "2019-03-29 10:43:38",
        "updated_at": "2019-03-29 10:43:38",
        "hugs": [
            "hug-id",
            "hug-id",
        ],
        "purchased_at_date": "2019-03-29",
        "purchased_at_time": "10:43:38"
    },
    "embedded": []
}
HTTP/1.1 201 created

{
    "data": {
        "id": "transaction-id",
        "retail": "transaction-cost",
        "created_at": "2019-03-29 10:43:38",
        "updated_at": "2019-03-29 10:43:38",
        "hugggs": [
            "hug-id",
            "hug-id",
        ],
        "purchased_at_date": "2019-03-29",
        "purchased_at_time": "10:43:38"
    },
    "embedded": [
        "hugs": [
            {...}
            {...}
        ],
        "products": [
            {...}
        ],
        "brands": [
            {...}
        ],
        "stores": [
            {...}
        ],
    ]
}