Docs / API reference

Shortcodes

Your paybills and tills. View them, configure them and assign them to wallets.

The Shortcode object

A paybill or till number. Each one settles to the wallet you assign. A paybill can validate account numbers before the customer is charged.

Attributes

idstring
Unique identifier, starting sc_.
typestring
Paybill or till.
One of paybill, till
numberstring
The number customers pay.
namestring
A name you choose.
statusstring
Whether it takes payments.
One of active, pending, suspended
wallet_idstring | null
The wallet payments to this shortcode land in.
callback_urlstring
Where Pitisha sends each payment as a signed webhook.
validationboolean
Paybills only. Reject payments whose account number does not fit account_format.
account_formatstring
The account number rule.

Example object

{
  "id": "sc_4012345",
  "object": "shortcode",
  "type": "paybill",
  "number": "4012345",
  "name": "Main paybill",
  "status": "active",
  "wallet_id": "wal_main",
  "callback_url": "https://api.example.com/pitisha/callback",
  "validation": true,
  "account_format": "Invoice number, 6 digits",
  "livemode": false,
  "created_at": "2026-06-12T09:30:00+03:00"
}

GET/v1/shortcodes

List shortcodes

All shortcodes in this mode.

Query parameters

wallet_idstring
Only shortcodes on this wallet.
limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/shortcodes" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sc_4012345",
      "object": "shortcode",
      "type": "paybill",
      "number": "4012345",
      "name": "Main paybill",
      "status": "active",
      "wallet_id": "wal_main",
      "callback_url": "https://api.example.com/pitisha/callback",
      "validation": true,
      "account_format": "Invoice number, 6 digits",
      "livemode": false,
      "created_at": "2026-06-12T09:30:00+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

GET/v1/shortcodes/{id}

Retrieve a shortcode

Fetch one shortcode.

Path parameters

idstringrequired
The shortcode id.

Errors

404 not_found

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/shortcodes/ID_FROM_RESPONSE" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "id": "sc_4012345",
  "object": "shortcode",
  "type": "paybill",
  "number": "4012345",
  "name": "Main paybill",
  "status": "active",
  "wallet_id": "wal_main",
  "callback_url": "https://api.example.com/pitisha/callback",
  "validation": true,
  "account_format": "Invoice number, 6 digits",
  "livemode": false,
  "created_at": "2026-06-12T09:30:00+03:00"
}

PATCH/v1/shortcodes/{id}

Configure a shortcode

Assign it to a wallet and set how it validates.

Setting wallet_id is how you assign a shortcode to a wallet. From then on, every payment to it lands there.

Path parameters

idstringrequired
The shortcode id.

Body parameters

wallet_idstring | null
The wallet to settle to, or null to unassign.
namestring
A new name.
callback_urlstring
A new callback URL.
validationboolean
Paybills only.
account_formatstring
The account number rule.

Errors

404 not_found
400 invalid_request
403 permission_denied

See Errors for what each means.

curl -X PATCH "$PITISHA_API/v1/shortcodes/ID_FROM_RESPONSE" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "wal_shop",
    "validation": true
  }'

{
  "id": "sc_4012345",
  "object": "shortcode",
  "type": "paybill",
  "number": "4012345",
  "name": "Main paybill",
  "status": "active",
  "wallet_id": "wal_shop",
  "callback_url": "https://api.example.com/pitisha/callback",
  "validation": true,
  "account_format": "Invoice number, 6 digits",
  "livemode": false,
  "created_at": "2026-06-12T09:30:00+03:00"
}