Check out the Wallet API overview to understand how Okra uses wallets to handle payments for the services and products that you use, and how you can manage your wallets.

Get wallet

post /wallet/get

HTTP bearer bearer

This operation returns a wallet object based on JWT token that you are using to authorize your request. The body of the request should be empty.

or null

Request

null

Response

Examples Schema

A successful response of the get wallet operation.

[
  {
    "status": "success",
    "message": "Wallet successfully retrieved!",
    "data": {
      "wallet": {
        "_id": "14550e9c2264c151c9cfc1e4",
        "auto_topup": {
          "status": true,
          "payment_method": "xxxxxxxxxxxxxxxxxxxxxxxx",
          "topup_amount": 101,
          "available_balance_threshold": 100,
          "currency": "USD",
          "amount": 101
        },
        "notifications": {
          "available_balance": {
            "status": true,
            "min": 900,
            "schedule": "hourly",
            "emails": [
              "test+user1@okra.ng",
              "test+user2@okra.ng"
            ]
          }
        },
        "created_at": "2023-05-05T14:12:00.807Z",
        "credits": 1.35364000000007,
        "last_updated": "2023-05-10T09:32:13.861Z",
        "payment_wallet": 1590999,
        "current_project": "1ff62b99aea7a57a5c3baa01",
        "current_project_name": "My Project"
      }
    }
  }
]

An example response of a successful get wallet operation.

status

string

message

string

data

object (data)

wallet

object (wallet)

Returns details about an Okra wallet.

_id

boolean

The unique ID of a wallet record.

notifications

object (notifications)

Returns details about notifications for a wallet.

available_balance

object (available_balance)

Returns details about the low wallet balance notification.

status

boolean

Shows whether the low wallet balance notification is enabled.

min

number

Returns the threshold amount that triggers a low balance notification.

schedule

string

Returns the set frequency of the low wallet balance notification.

Enum
  • hourly
  • twice_daily
  • tri_daily
  • four_daily
  • daily

emails

array[string]

Returns the email addresses that the API sends notifications to.

string

credits

number

Shows the current credit balance available in a wallet.

auto_topup

object (auto_topup)

Returns details about automatic top-up settings for a wallet.

status

boolean

Shows whether automatic top-up is enabled for a wallet.

currency

string

Shows the currency used to purchase credits for automatic top-ups.

available_balance_threshold

number

Shows the threshold amount that triggers an automatic top-up.

topup_amount

number

Shows the amount of credits that is added to a wallet during an automatic top-up.

amount

number

Shows the amount of money that is used to purchase credits for an automatic top-up.

payment_method

string

uuid

Returns the reference ID of the card that is used as a payment method.

created_at

string

Indicates the date and time when the wallet was created. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

last_updated

string

Indicates the date and time when the wallet was last updated. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

payment_wallet

number

Returns the total amount of money that is available in your Payments balance via the Payments API.

current_project

string

Returns the ID of the project that the wallet belongs to.

current_project_name

string

Returns the name of the project that the wallet belongs to.

List wallets

post /wallet/list

HTTP bearer bearer

The request for the list wallets operation.

page

int

i32

Page determines the page that the API returns in the response. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

limit

int

i32

Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

project

string

The unique ID of an Okra project.

id

string

The unique ID of an Okra wallet.

term

string

A search term that filters for project name.

Request

{
  "term": "My project",
  "page": 1,
  "limit": 10
}

Response

Examples Schema

A successful response of the list wallets operation.

[
  {
    "summary": "Wallets returned successfully",
    "description": "An example response of a successful list wallets operation.",
    "value": [
      {
        "status": "success",
        "message": "Wallet(s) successfully retrieved!",
        "data": {
          "wallets": [
            {
              "id": "13cfa4261521184c8cf428c3",
              "current_project": "131f47360d4cdca777a7e671",
              "current_project_name": "My Project",
              "company": {
                "_id": "131f4736b5dba8be3595cdbb",
                "name": "BUGA MOTORS GLOBAL INVESTMENT LIMITED"
              },
              "auto_topup": {
                "status": true,
                "payment_method": "xxxxxxxxxxxxxxxxxxxxxxxx",
                "topup_amount": 101,
                "available_balance_threshold": 100,
                "currency": "USD",
                "amount": 101
              },
              "notifications": {
                "available_balance": {
                  "status": true,
                  "min": 900,
                  "schedule": "hourly",
                  "emails": [
                    "test+user1@okra.ng",
                    "test+user2@okra.ng"
                  ]
                }
              },
              "credits": 1000,
              "payment_wallet": 0
            }
          ],
          "total": null,
          "pagination": {
            "totalDocs": null
          }
        }
      }
    ]
  }
]

An example response of a successful get wallet operation.

status

string

message

string

data

object (data)

wallets

array[object (A wallet object.)]

Returns all of your wallets as an array of objects.

A wallet object.

object (A wallet object.)

wallet

object (wallet)

Returns details about an Okra wallet.

_id

string

The unique ID of a wallet record.

current_project

string

Returns the ID of the project that the wallet belongs to.

current_project_name

string

Returns the name of the project that the wallet belongs to.

notifications

object (notifications)

Returns details about notifications for a wallet.

available_balance

object (available_balance)

Returns details about the low wallet balance notification.

status

boolean

Shows whether the low wallet balance notification is enabled.

min

number

Returns the threshold amount that triggers a low balance notification.

schedule

string

Returns the set frequency of the low wallet balance notification.

Enum
  • hourly
  • twice_daily
  • tri_daily
  • four_daily
  • daily

emails

array[string]

Returns the email addresses that the API sends notifications to.

string

auto_topup

object (auto_topup)

Returns details about automatic top-up settings for a wallet.

status

boolean

Shows whether automatic top-up is enabled for a wallet.

currency

string

Shows the currency used to purchase credits for automatic top-ups.

available_balance_threshold

number

Shows the threshold amount that triggers an automatic top-up.

topup_amount

number

Shows the amount of credits that is added to a wallet during an automatic top-up.

amount

number

Shows the amount of money that is used to purchase credits for an automatic top-up.

payment_method

string

uuid

Returns the reference ID of the card that is used as a payment method.

company

object (company)

Returns details about the company that the wallet belongs to.

_id

string

The unique ID of the company that the wallet belongs to.

name

string

The name of the company that the wallet belongs to.

credits

number

Shows the current credit balance available in a wallet.

payment_wallet

string

Returns the total amount of money that is available in your Payments balance via the Payments API.

total

string

Shows the total number of wallets.

Example
"1000"

pagination

object (pagination)

totalDocs

int

i32

The total number of results that match the request.

limit

int

i32

Returns the value of the limit parameter. Limit sets the number of results that the API returns in a single page. If you do not specify a value for limit, the API will limit the response to 10 results per page.

hasPrevPage

boolean

Shows when a previous page of results is available. This field always returns true when the value of page is greater than 1.

hasNextPage

boolean

Shows when a next page of results is available. When true, Okra recommends that you make subsequent requests to retrieve the following pages of results.

page

int

i32

Returns the number of the current page. For example, if you set page to 1 in your request, the API will return the first page of results in the response.

totalPages

int

i32

The total number of pages that the API returns.

pagingCounter

int

i32

The index number of the first result on the current page. For example, if the value of page is 2 and limit is set to 10, then pagingCounter returns 11.

prevPage

string or null

The number of previous result pages. If the value of page is 1 and there is no previous page, the value of prevPage is null.

nextPage

string or null

The number of following result pages. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

Check wallet balance

post /wallet/balance/check

HTTP bearer bearer

The request for the check wallet balance operation.

project

string

The unique ID of an Okra project.

id

string

The unique ID of an Okra wallet.

Request

{
  "project": "1dadfa049f45083b5e14d75a"
}

Response

Examples Schema

A successful response of the check wallet balance operation.

[
  {
    "status": "success",
    "message": "Balance successfully fetched!",
    "data": {
      "balance": [
        {
          "auto_topup": {
            "status": true,
            "payment_method": "xxxxxxxxxxxxxxxxxxxxxxxx",
            "topup_amount": 101,
            "available_balance_threshold": 100,
            "currency": "USD",
            "amount": 101
          },
          "notifications": {
            "available_balance": {
              "status": true,
              "min": 900,
              "schedule": "hourly",
              "emails": [
                "test+user1@okra.ng",
                "test+user2@okra.ng"
              ]
            }
          },
          "credits": 1000,
          "payment_wallet": 0,
          "current_project": "1dadfa049f45083b5e14d75a",
          "current_project_name": "My Project",
          "last_updated": "2023-03-13T00:32:51.252Z"
        }
      ]
    }
  }
]

An example response of a successful check wallet balance operation.

Check wallet balance

array[object (The response of the check wallet balance operation.)]

This operation returns the balance of a wallet based on the project ID. If you do not specify a value for project in your request, the API will return all balances across all of your Okra projects in an array.

The response of the check wallet balance operation.

object (The response of the check wallet balance operation.)

status

string

message

string

data

object (data)

balance

array[object (An Okra wallet balance object.)]

Returns details about the credit balance of an Okra wallet.

An Okra wallet balance object.

object (An Okra wallet balance object.)

notifications

object (notifications)

Returns details about notifications for a wallet.

available_balance

object (available_balance)

Returns details about the low wallet balance notification.

status

boolean

Shows whether the low wallet balance notification is enabled.

min

number

Returns the threshold amount that triggers a low balance notification.

schedule

string

Returns the set frequency of the low wallet balance notification.

Enum
  • hourly
  • twice_daily
  • tri_daily
  • four_daily
  • daily

emails

array[string]

Returns the email addresses that the API sends notifications to.

string

auto_topup

object (auto_topup)

Returns details about automatic top-up settings for a wallet.

status

boolean

Shows whether automatic top-up is enabled for a wallet.

currency

string

Shows the currency used to purchase credits for automatic top-ups.

available_balance_threshold

number

Shows the threshold amount that triggers an automatic top-up.

topup_amount

number

Shows the amount of credits that is added to a wallet during an automatic top-up.

amount

number

Shows the amount of money that is used to purchase credits for an automatic top-up.

payment_method

string

uuid

Returns the reference ID of the card that is used as a payment method.

credits

number

Shows the current credit balance available in a wallet.

payment_wallet

string

Returns the total amount of money that is available in your Payments balance via the Payments API.

current_project

string

Returns the ID of the project that the wallet belongs to.

current_project_name

string

Returns the name of the project that the wallet belongs to.

last_updated

string

Indicates the date and time when the wallet was last updated. The timestamp value follows the ISO 8601 format, for example 2022-11-20.

Was this page helpful?