PurplX - Cards

Purpl provides 2 types of Cards: virtual and physical. Virtual Cards can be instantly requested, automatically activated, and can be used for payments immediately. Physical Cards need extra details upon request, like the delivery details, and are activated separately.

Sandbox: http://api.sandbox.purplx.me
Live: http://api.purplx.me

Needed API resource scope

card card-transaction

Resources

Wallet: PurplX - Wallets

Card:

Name	Type	Notes
`url`	URL	The URL of the Card resource.
`id`	Integer	The unique ID of the Card resource.
`app_user`	URL	The AppUser who owns the Card resource.
`mobile_number`	Phone	The mobile number for the Card resource. This is needed specially for payments that need OTPs.
`first_name`	String	The first name of the cardholder. This is mostly the first name of the AppUser owner.
`last_name`	String	The last name for the cardholder. This mostly the last name of the AppUser owner.
`company_name`	String	The company name of the cardholder.
`name`	String	The useful name for the Card. This is not the cardholder name, but any user-friendly identifier for the Card that tells its purpose or what it’s for.
`type`	Enum	The type of the Card: `virtual` or `physical`.
`delivery_details`	Object	The delivery details. This is required when requesting a Physical Card. This field is an object, with the expected fields `address`, `phone_number`.
`provider`	String	The Card provider.
`provider_reference`	String	The provider’s unique reference number for the Card.
`status`	Enum	The status of the Card. Can be:
• `created`: The initial status of the Card upon requesting. The Card cannot be used for payments yet.
• `active`: The Card’s now active. The Card can now be used for payments.
• `frozen`: The Card’s locked, or temporarily inactive. The Card cannot be used for any payments.
• `terminated`: The Card’s closed, and can never be used for payments again. Terminating a Card with still some balance in it is not allowed.
`masked_card_number`	String	The masked version of the Card number.
`status_history`	Object	A list that records the status changes of the Card.
`blocked_countries`	Object	A list of blocked countries. Payments cannot be made in these blocked countries. The country format should be ISO 3166-1 alpha-3 (ex. LBN).
`theme`	String	A small field for storing the style identification of the Card. This is mostly used for front-end displays.
`datetime_created`	Datetime	A field that records the datetime of when the Card was requested.
`datetime_updated`	Datetime	A field that records the datetime of when the Card got updated.
`card_number`	String	The complete Card number.
`card_name`	String	The Card name that is set automatically by the provider.
`expiry_date`	String	The expiry date of the Card. It’s a 4-digit string. The first 2 digits are the month. The last 2 digits are the year.
`balance`	Object	The balance of the Card.

Card Transaction:

Name	Type	Notes
`url`	URL	The URL of the Card Transaction.
`id`	Integer	The unique ID of the Card Transaction.
`type`	Enum	The type of the Card Transaction. Can only be:
• `debit`: A debiting transaction that deducts the balance of the Card.
• `credit`: A crediting transaction that adds to the balance of the Card.
`amount`	Object	The requested amount for funding a Card from a Wallet balance, or the requested amount for moving funds from a Card to a Wallet.
`amounts`	Object	The amounts breakdown. This is mostly usable for actual Card payments.
`fx_rate`	String	The FX rate.
`transaction_type`	String	The transaction type as specified by the Card provider.
`status`	Enum	The status of the Card Transaction. Can only be:
• `success`
• `failed`
• `reversed`
• `refunded`
`provider_reference`	String	The provider’s reference number for the Card Transaction.
`card`	Object	The Card from which the Card Transaction belongs to.
`transaction_datetime`	Datetime	The field that records when the Card Transaction actually happened.
`datetime_created`	Datetime	The field that records when the Card Transaction is created in the database.
`datetime_updated`	Datetime	The field that records when the Card Transaction is updated.
`source`	Object	The fund source. This is used to move funds from a Wallet to a Card.
`destination`	Object	The fund destination. This is used to move funds from a Card to a Wallet.
`country`	String	The country of payment.
`merchant`	Object	The merchant details.

Requesting a Virtual Card

Example:

curl --location --request POST 'http://localhost:8000/app-users/32100/cards/' \
--header 'Authorization: Bearer A5vKeltR3fyJRmqjz4G7ytGGl1e86p' \
--header 'Accept: application/vnd.purplme+json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+639453045616",
    "type": "virtual"
}' \
| jq

{
  "url": "http://localhost:8000/cards/215/",
  "id": 215,
  "app_user": "http://localhost:8000/app-users/32100/",
  "mobile_number": "+639453045616",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "",
  "name": "Purpl Card",
  "type": "virtual",
  "delivery_details": {},
  "provider": "BLF_CTM",
  "provider_reference": "41083830",
  "status": "active",
  "masked_card_number": "************6406",
  "status_history": [
    {
      "status": "created",
      "updatedAt": 1788362500914,
      "datetime_updated": "2026-09-02T15:21:40.914280+00:00"
    },
    {
      "status": "active",
      "updatedAt": 1788362505249,
      "datetime_updated": "2026-09-02T15:21:45.249579+00:00"
    }
  ],
  "blocked_countries": null,
  "theme": null,
  "datetime_created": "2026-09-02T15:21:40.914571Z",
  "datetime_updated": "2026-09-02T15:21:45.249971Z",
  "card_number": "4560780325636406",
  "card_name": "PURPL SAL",
  "expiry_date": "0930",
  "balance": {
    "available": {
      "value": 0.0,
      "currency": "USD"
    },
    "blocked": {
      "value": 0.0,
      "currency": "USD"
    }
  },
  "credit_limit": {
    "value": 0.0,
    "currency": "USD"
  },
  "add_limit": {
    "value": 0.0,
    "currency": "USD"
  }
}

Virtual Cards are free, right now, so the funds_source field is not required.
Virtual Cards are activated automatically after it’s requested, and can be used for payments immediately.

Requesting a Physical Card

Example:

curl --location --request POST 'http://localhost:8000/app-users/32100/cards/' \
--header 'Authorization: Bearer A5vKeltR3fyJRmqjz4G7ytGGl1e86p' \
--header 'Accept: application/vnd.purplme+json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+639453045616",
    "type": "physical",
    "delivery_details": {
        "address": "Beirut",
        "phone_number": "+639453045616"
    },
    "funds_source": {
        "type": "wallet",
        "id": "f5a603552b024d7f95ce2e75300e2b82"
    }
}' \
| jq

{
  "url": "http://localhost:8000/cards/217/",
  "id": 217,
  "app_user": "http://localhost:8000/app-users/32100/",
  "mobile_number": "+639453045616",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "",
  "name": "Purpl Card",
  "type": "physical",
  "delivery_details": {
    "address": "Beirut",
    "phone_number": "+639453045616"
  },
  "provider": "BLF_CTM",
  "provider_reference": "41083920",
  "status": "created",
  "masked_card_number": null,
  "status_history": [
    {
      "status": "created",
      "updatedAt": 1788362949407,
      "datetime_updated": "2026-09-02T15:29:09.407281+00:00"
    }
  ],
  "blocked_countries": null,
  "theme": null,
  "datetime_created": "2026-09-02T15:29:09.407469Z",
  "datetime_updated": "2026-09-02T15:29:16.495450Z",
  "card_number": null,
  "card_name": "PURPL SAL",
  "expiry_date": "0930",
  "balance": {
    "available": {
      "value": 0.0,
      "currency": "USD"
    },
    "blocked": {
      "value": 0.0,
      "currency": "USD"
    }
  },
  "credit_limit": {
    "value": 0.0,
    "currency": "USD"
  },
  "add_limit": {
    "value": 0.0,
    "currency": "USD"
  }
}

Requesting a Physical Card requires the delivery_details.