Request a Single Use Card

Request

🔒 Private label — contact sales. Requires a private-label entitlement on your API client.

Creates a Single Use Card (SUC) approval request for an employee.

Customer resolution transaction dump so it is available on expense records without an additional lookup.

Security

oauth2ClientCredentials(Required scopes: cards:write)

org_wallet_refstring

Organization wallet reference, defaults to "1" if not provided

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired

employee_idstringrequired

Employee ID of the requesting employee

Example:"EMP001"

org_wallet_refstring

Organization wallet reference

Example:"1"

amountnumber

Requested amount. Can be 0 for just_in_time funded cards (amount resolved when card is run).

Example:5000

currencystring

Currency code (defaults to "KES")

Example:"KES"

notesstring

Notes / purpose of the card request

Example:"Purchase office supplies from vendor"

vendor_idstring

Vendor / merchant ID

Example:"VND_001"

vendor_namestring

Vendor / merchant display name

Example:"Office Supplies Co."

customer_idstring

Customer ID (legacy — prefer sending the full customer object)

Example:"69dd1e56d2756bba9fa9983b"

customer_namestring

Customer display name (legacy — prefer sending the full customer object)

Example:"Giraffe Center"

customerobject(CustomerObjectDto)

Full customer object from the tenant DB. When provided, the downstream service uses this directly instead of fetching by customer_id.

subcategory_idstring

Expense sub-category ID

Example:"CAT_OFFICE"

tagsArray of objects(TagObjectDto)

Array of expense tag objects selected by the user

Example:

[
  {
    "_id": "68a2de3b73b7e53060aca3df",
    "tag_group": "68a2de0194af89ac7c37aaa9",
    "name": "Safaricom",
    "employee": { … }
  }
]

attachmentsArray of strings

Array of attachment URLs or file references

Example:

[
  "https://storage.example.com/receipt.pdf"
]

requisition_referencestring

Internal requisition reference number

Example:"REQ-2024-001"

curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/cards/single-use/request \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "employee_id": "EMP001",
    "amount": 5000,
    "currency": "KES",
    "notes": "Purchase office supplies",
    "subcategory_id": "CAT_OFFICE",
    "customer": {
      "_id": "69dd1e56d2756bba9fa9983b",
      "name": "Giraffe Center",
      "email": "giraffe@acme.com",
      "phone": "+254700000012",
      "address": "123 Karen Street, Nairobi",
      "type": "regular",
      "status": "active",
      "person": [
        "123"
      ],
      "taxPin": "A123456789Z"
    }
  }'

Responses

Single use card request created successfully

Bodyapplication/json

statusstringrequired

Outcome of the SUC request. AUTO_APPROVED means the card is issued immediately; PENDING_APPROVAL means it is queued for an approver.

Enum:"AUTO_APPROVED""PENDING_APPROVAL"

Example:"PENDING_APPROVAL"

refstringrequired

Approval / card reference

Example:"O-A1B2C3D4"

messagestringrequired

Human-readable result message

Example:"Single use card request submitted successfully."

Response

{
  "status": "PENDING_APPROVAL",
  "ref": "O-A1B2C3D4",
  "message": "Single use card request submitted successfully."
}