Skip to content
Pipevest Developers

Stock Purchase View

The stock purchase view allows the user to confirm an amount to purchase for a given stock.

This flow is particularly important given that a POST request must be made in order to create the purchase order request.

Accessing the stock purchase view

Section titled “Accessing the stock purchase view”

Pass 1 as the option key to the choice parameter.

Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/ussd/process \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"sessionId": "<session-id>", "choice": "1"}'

Example Response

{
    "message": "USSD request processed successfully",
    "data": {
        "sessionId": "ussd_5310deea137a9cd999b02ae68a7bbbec",
        "currentState": "BUY_STOCK",
        "menu": {
            "state": "BUY_STOCK",
            "text": "Buy Apple Inc. (AAPL)\n\nSelect amount to invest:",
            "options": [
                {
                    "key": "1",
                    "label": "ZK22.00",
                    "nextState": "PURCHASE_CONFIRMATION",
                    "data": {
                        "amount": 22
                    }
                },
                {
                    "key": "2",
                    "label": "ZK112.00",
                    "nextState": "PURCHASE_CONFIRMATION",
                    "data": {
                        "amount": 112
                    }
                },
                {
                    "key": "3",
                    "label": "ZK562.00",
                    "nextState": "PURCHASE_CONFIRMATION",
                    "data": {
                        "amount": 562
                    }
                },
                {
                    "key": "4",
                    "label": "Enter custom amount",
                    "nextState": "ENTER_CUSTOM_PURCHASE_AMOUNT"
                },
                {
                    "key": "0",
                    "label": "Back",
                    "nextState": "SELECT_STOCK"
                }
            ],
            "isEndState": false
        },
        "ussdText": "Buy Apple Inc. (AAPL)\n\nSelect amount to invest:\n\n1. ZK22.00\n2. ZK112.00\n3. ZK562.00\n4. Enter custom amount\n0. Back",
        "expiresAt": "2025-11-06T14:58:33.942Z"
    }
}
What the customer sees
Buy Apple Inc. (AAPL)

Select amount to invest:

1. ZK22.00
2. ZK112.00
3. ZK562.00
4. Enter custom amount
0. Back

Confirming order purchase request

Section titled “Confirming order purchase request”
Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/ussd/process \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --data '{"sessionId": "<session-id>", "choice": "1"}'
{
    "message": "USSD request processed successfully",
    "data": {
        "sessionId": "ussd_5310deea137a9cd999b02ae68a7bbbec",
        "currentState": "PURCHASE_CONFIRMATION",
        "menu": {
            "state": "PURCHASE_CONFIRMATION",
            "text": "Confirm stock purchase:\n\nStock: Apple Inc. (AAPL)\nAmount: ZK22.00\n\nPress \"1\" to confirm purchase and agree to terms and conditions (pipevest.com/terms).",
            "options": [
                {
                    "key": "1",
                    "label": "Confirm",
                    "nextState": "PURCHASE_SUCCESS"
                },
                {
                    "key": "0",
                    "label": "Back",
                    "nextState": "BUY_STOCK"
                }
            ],
            "isEndState": false
        },
        "ussdText": "Confirm stock purchase:\n\nStock: Apple Inc. (AAPL)\nAmount: ZK22.00\n\nPress \"1\" to confirm purchase and agree to terms and conditions (pipevest.com/terms).\n\n1. Confirm\n0. Back",
        "expiresAt": "2025-11-06T14:58:33.942Z"
    }
}
What the customer sees
Confirm stock purchase:

Stock: Apple Inc. (AAPL)
Amount: ZK22.00

Press "1" to confirm purchase and agree to terms and conditions (pipevest.com/terms).

1. Confirm
0. Back

Stock Purchase Example

Section titled “Stock Purchase Example”
USSD Stock Purchase View

Check out an example of the ussd stock purchase view