Create Purchase Intent

Create a Purchase Intent to generate temporary credentials (virtual card, network token, etc) for a specific payment method, enabling secure transactions on behalf of the user.

Request

POST /projects/:projectId/purchase-intents

curl -X POST \
  https://api.basistheory.ai/projects/:projectId/purchase-intents \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityId": "user-12345",
    "credentialType": "virtual-card",
    "paymentMethodId": "26859380-7829-4ee1-8a0a-38927881e7ef",
    "mandates": [
      {
        "type": "maxAmount",
        "value": "100",
        "details": {
          "currency": "840"
        }
      },
      {
        "type": "merchantMcc",
        "value": "140"
      }
    ]
  }'

URL Parameters

Parameter	Required	Type	Default	Description
`projectId`	true	string	`null`	The project ID (must match JWT issuer).

Request Parameters

Parameter	Required	Type	Default	Description
`entityId`	true	string	`null`	Unique user identifier (must match JWT `sub` claim).
`credentialType`	true	string	`null`	The type of credential to create (“virtual-card”, “network-token”, “pan”).
`paymentMethodId`	true	string	`null`	The payment method ID to create credentials from.
`mandates`	true	Mandate Object[]	`null`	Array of spending limits and restrictions for the credential.

Mandate Object

Property	Required	Type	Description
`type`	true	string	The mandate type.
`value`	true	string	The mandate value.
`details`	conditional	object	Details about the mandate. Vary by mandate.

Response

{
  "id": "0b1ac700-c1a7-46b0-a166-809e5aac4dc3",
  "entityId": "user-12345",
  "credentialType": "virtual-card",
  "status": "active",
  "createdAt": "2025-01-15T14:00:00Z",
  "expiresAt": "2025-01-16T14:00:00Z",
  "card": {
    "number": "2222030198005808",
    "expirationMonth": "07",
    "expirationYear": "2028",
    "cvc": "211"
  }
}

Response Properties

Property	Type	Description
`id`	string	Unique purchase intent identifier.
`entityId`	string	User ID that owns this purchase intent.
`credentialType`	string	Type of credential created (“virtual-card”, “network-token”, “pan”).
`status`	string	Purchase intent status (typically “active”).
`createdAt`	string	ISO 8601 timestamp when the purchase intent was created.
`expiresAt`	string	ISO 8601 timestamp when the credentials expire (typically 24 hours).
`card`	Card Object	Virtual card details (when credentialType is “virtual-card”).
`token`	Token Object	Network token details (when credentialType is “network-token”).
`pan`	PAN Object	PAN details (when credentialType is “pan”).

Virtual Card Object

Property	Type	Description
`number`	string	Temporary virtual card number for one-time use.
`expirationMonth`	string	Virtual card expiration month in `MM` format.
`expirationYear`	string	Virtual card expiration year in `YYYY` format.
`cvc`	string	Virtual card security code.

Token Object

Property	Type	Description
`number`	string	Network-tokenized card number.
`expirationMonth`	string	Token expiration month in `MM` format.
`expirationYear`	string	Token expiration year in `YYYY` format.
`cryptogram`	string	Token cryptogram for transaction authentication.

PAN Object

Property	Type	Description
`number`	string	The original card number (PAN).
`expirationMonth`	string	Card expiration month in `MM` format.
`expirationYear`	string	Card expiration year in `YYYY` format.
`cvc`	string	Card security code.

Security Note: The PAN credential type exposes the original card number and should only be used in highly secure, PCI-compliant environments.

Error Handling

{
  "error": {
    "status": 400,
    "type": "invalidRequest",
    "title": "The request is invalid",
    "message": "Request is invalid, check details object for details.",
    "details": {
      "fields": {
        "credentialType": "Must be one of: virtual-card, network-token, pan."
      }
    }
  }
}

Credential Types

Available Credential Types

Type	Description	Status Scenarios
`virtual-card`	Generates a virtual card number for one-time use	`active`
`network-token`	Generates a network tokenized credential	`active`, `verify`
`pan`	Uses the original card PAN	`active`

Status Meanings

Status	Description
`active`	Credential is ready for immediate use
`verify`	Additional verification required before use
`unavailable`	Credential type not available for this payment method

Mandate Types

Available Mandate Types

Type	Description	Required Details
`maxAmount`	Maximum transaction amount	`currency` (ISO 4217 code)
`merchantMcc`	Merchant category code restriction	None
`expirationDate`	Credential expiration date	`date` (ISO 8601)
`usageLimit`	Maximum number of uses	`count` (integer)

Example Mandates

{
  "mandates": [
    {
      "type": "maxAmount",
      "value": "500.00",
      "details": {
        "currency": "840"
      }
    },
    {
      "type": "merchantMcc",
      "value": "5411"
    },
    {
      "type": "expirationDate", 
      "value": "2024-12-31T23:59:59Z"
    },
    {
      "type": "usageLimit",
      "value": "1",
      "details": {
        "count": 1
      }
    }
  ]
}