Cards

Use the Cards API to list cards, retrieve a card, inspect available balance, set or update its spending limits, and enable or disable ATM withdrawals and online payments. Monetary values are integer cents.

The card model

Name
id
Type
string · required
Description
Unique card identifier, for example CRD1000000000.
Name
last4
Type
string | null · required
Description
Last four digits of the card number. null when the card is not activated.
Name
nickname
Type
string · required
Description
Nickname assigned to the card.
Name
cardHolder
Type
CardHolder · required
Description
Cardholder details. Includes id, fullName, optional userExternalIdOne, userExternalIdTwo, and userExternalIdThree, and a nullable department object containing id and name.
Name
limits
Type
CardLimits · required
Description
Current daily, monthly, atm, and nullable approvalBased limits.
Name
availableBalance
Type
integer | null · required
Description
Amount currently available to spend, in cents.
For non-approval-based cards, this is the minimum of the remaining daily, monthly, and ATM limits after subtracting usage for each period.
For example, with a daily limit of EGP 5,000, a monthly limit of EGP 20,000, and an ATM limit of EGP 10,000, spending EGP 1,000 today and EGP 5,000 this month with no ATM transactions leaves an available balance of EGP 4,000. The remaining daily limit is the most restrictive in this case.
For approval-based cards, this is the amount still available after current spending, pending transactions, and outstanding cash.
This is null if the card is not activated.

Card example

{
  "id": "CRD1000000000",
  "last4": "1234",
  "nickname": "Business Travel Card",
  "cardHolder": {
    "id": "USR1000000000",
    "fullName": "Sara Amr",
    "userExternalIdOne": "EMP-100",
    "userExternalIdTwo": "COST-20",
    "userExternalIdThree": "REGION-3",
    "department": {
      "id": "TAG1000000000",
      "name": "Sales"
    }
  },
  "limits": {
    "daily": 500000,
    "monthly": 2000000,
    "atm": 400000,
    "approvalBased": null
  },
  "availableBalance": 150000
}

Card limits

Name
daily
Type
integer · required
Description
Daily spending limit in cents. Range: -100000000 to 100000000.
Name
monthly
Type
integer · required
Description
Monthly spending limit in cents. Range: -300000000 to 300000000.
Name
atm
Type
integer · required
Description
Monthly ATM withdrawal limit in cents. Range: -300000000 to 300000000.
Name
approvalBased
Type
integer | null · required
Description
Approval-based limit in cents. Range: -99999999999 to 99999999999, or null for a non-approval-based card.

For approval-based cards, the other limit fields are set to their maximum values and are not useful for determining how much can be spent. Use availableBalance for the current spendable amount.

GET/v1/card

List cards

Returns cards using cursor pagination.

Query parameters

Name
cursor
Type
string
Description
Cursor returned as nextCursor by the previous page.
Name
limit
Type
integer
Description
Maximum number of cards to return. Defaults to 10.

Request

GET

/v1/card

curl -G https://p.swypex.com/v1/card \
  -H "Authorization: Bearer {access_token}" \
  --data-urlencode "limit=10"

Response

{
  "cards": [
    {
      "id": "CRD1000000000",
      "last4": "1234",
      "nickname": "Business Travel Card",
      "cardHolder": {
        "id": "USR1000000000",
        "fullName": "Sara Amr",
        "department": { "id": "TAG1000000000", "name": "Sales" }
      },
      "limits": {
        "daily": 500000,
        "monthly": 2000000,
        "atm": 400000,
        "approvalBased": null
      },
      "availableBalance": 150000
    }
  ],
  "nextCursor": "eyJpZCI6IkNSRDEwMDAwMDAwMDAifQ=="
}

GET/v1/card/{id}

Retrieve a card

Returns one card by its unique ID. The response is a card object.

Name
id
Type
string · required
Description
Card ID supplied in the path.

Request

GET

/v1/card/CRD1000000000

curl https://p.swypex.com/v1/card/CRD1000000000 \
  -H "Authorization: Bearer {access_token}"

Response

{
  "id": "CRD1000000000",
  "last4": "1234",
  "nickname": "Business Travel Card",
  "cardHolder": {
    "id": "USR1000000000",
    "fullName": "Sara Amr",
    "department": { "id": "TAG1000000000", "name": "Sales" }
  },
  "limits": {
    "daily": 500000,
    "monthly": 2000000,
    "atm": 400000,
    "approvalBased": null
  },
  "availableBalance": 150000
}

PUT/v1/card/{id}/limits

Set card limits

Sets absolute spending limits and enables or disables card features. You can update limits and features together, or update features alone. Null or omitted fields keep their current settings. Provide at least one non-null limit or feature flag; false counts as a provided feature flag.

Returns the updated card object.

Feature flags

Name
atmWithdrawalEnabled
Type
boolean | null · optional
Description
true enables ATM withdrawals; false disables them. null or omission leaves the current setting unchanged.
Name
onlinePaymentEnabled
Type
boolean | null · optional
Description
true enables online payments; false disables them. null or omission leaves the current setting unchanged.

These request fields are supported by PUT and are not returned in the card's limits object. PATCH continues to adjust numeric limits only.

For approval-based cards, set approvalBased to a non-null value and omit daily, monthly, and atm. Feature flags can be included with an approval-based limit update, or sent on their own to keep the existing limit.

Request

PUT

/v1/card/CRD1000000000/limits

curl -X PUT https://p.swypex.com/v1/card/CRD1000000000/limits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"daily":750000,"monthly":3000000,"atm":500000,"approvalBased":null,"atmWithdrawalEnabled":true,"onlinePaymentEnabled":false}'

Response excerpt

{
  "id": "CRD1000000000",
  "limits": {
    "daily": 750000,
    "monthly": 3000000,
    "atm": 500000,
    "approvalBased": null
  },
  "availableBalance": 150000
}

Update a feature with null limits

This request disables ATM withdrawals while preserving the existing limits and online-payment setting. All four limit fields can be null when at least one feature flag is true or false.

PUT request body

{
  "daily": null,
  "monthly": null,
  "atm": null,
  "approvalBased": null,
  "atmWithdrawalEnabled": false,
  "onlinePaymentEnabled": null
}

PATCH/v1/card/{id}/limits

Update card limits

Updates only the limit fields included in the merge-patch document. Provided amounts are added to the current limits; negative amounts reduce them. Omitted limits remain unchanged.

For approval-based cards, set approvalBased to a non-null value and omit daily, monthly, and atm.

Returns the updated card object.

Request

PATCH

/v1/card/CRD1000000000/limits

curl -X PATCH https://p.swypex.com/v1/card/CRD1000000000/limits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"daily":900000}'

Response excerpt

{
  "id": "CRD1000000000",
  "limits": {
    "daily": 900000,
    "monthly": 3000000,
    "atm": 500000,
    "approvalBased": null
  },
  "availableBalance": 150000
}