Requests

Planned — on our roadmap. This capability is documented so you can design your integration ahead of time. It is not yet enabled to call; for initial go-live, investment flows transact via USSD. If it is part of your integration plan, contact us. See what’s available today.

Requests allow the purchase of Instruments and the sell of Assets. This document will guide you on how to create, update and get request details.

Creating a Request

There are 2 types of requests:

• Purchase Request
• Sell Request

Purchase Request

Tip

Make a POST request to /requests/purchase

  curl --request POST \
    --url https://api.pipevest.com/v1/requests/purchase\
    --header 'Authorization: Bearer 123456' \
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Content-Type: application/json' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("authorization" "content-digest" "content-length" "content-type" "x-client-id" "x-idempotency-key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \
    --header 'X-Idempotency-Key: 123456' \
    ...
    --data '{"customerId": 123456, "currency": "ZMW", "instrumentId": 123456, "purchaseAmount": 100 }'

Sell Request

Tip

Make a POST request to /requests/sell

  curl --request POST \
    --url https://api.pipevest.com/v1/requests/sell\
    ...
    --data '{"customerId": 123456, "currency": "ZMW", "assetId": 123456, "sellAmount": 100 }'

Note

Instead of sellAmount, a sellPercentage can be provided.

Recurring Requests

Optionally, requests can be set to recurring mode:

  curl --request POST \
    --url https://api.pipevest.com/v1/requests/purchase\
    ...
    --data '{"customerId": 123456,..., "isRecurring": true, "schedule": "WEEKLY" }'

Updating Requests

If you need to cancel a request:

Tip

Make a PUT request to /requests

  curl --request PUT \
    --url https://api.pipevest.com/v1/requests\
    ...
    --data '{"shouldCancelRequest": true}'

Retrieving Requests

When requesting account details you can do so either by getting:

• A list of requests
• An account by a given Id

List of Requests

Tip

Make a GET request to /requests.

  curl --request GET \
    --url https://api.pipevest.com/v1/requests?customerId=123456\
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("authorization" "content-digest" "content-length" "content-type" "x-client-id" "x-idempotency-key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \

Note

This endpoint can be paginated and sorted.

Request by Id

Tip

Make a GET request to /requests/{requestId}

  curl --request GET \
    --url https://api.pipevest.com/v1/requests/123456\
    ...

Entity Reference

Property	Definition
requestId	Unique request identifier
customerId	Unique customer identifier
symbol	The symbol associated by the instrument
requestType	The type of request being made
status	The status of the request
currency	Associated currency
isRecurring	Determines whether the request should be in recurring mode
schedule	The recurring schedule in which the instrument should be purchased
createdAt	Created at unix timestamp
updatedAt	Updated at unix timestamp

Purchase Request Entity

Note

Includes the additional properties:

Property	Definition
instrumentId	Unique instrument identifier
purchaseAmount	The total purchase amount for an asset or group of assets

Sell Request Entity

Note

Includes the additional properties:

Property	Definition
assetId	Unique asset identifier
sellAmount	The total amount to sell from an asset or group of assets
sellPercentage	The percentage amount to sell from an asset or group of assets

Status

Name	Definition
PENDING	The request is currently in progress
COMPLETED	The request has complete processing
CANCELED	The request was cancelled
ERROR	The request ended in an error

Request Type

Name	Definition
PURCHASE	Sets the request to purchase mode
SELL	Sets the request to sell mode

Webhook Subscriptions

Subscription	Definition	Domain
REQUEST	Only events that deal with requests	Requests
REQUEST.CREATED	Triggered when a request is created	Requests
REQUEST.UPDATED	Triggered when a request is updated	Requests