Create Purchase Intent

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

Request

POST /projects/:projectId/purchase-intent

curl -X POST \
  https://api.basistheory.ai/projects/:projectId/purchase-intent \
  -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.00",
        "details": {
          "currency": "840",
          "period": "transaction"
        }
      },
      {
        "type": "expirationTime",
        "value": "2024-12-31T23:59:59Z",
        "details": {
          "timezone": "UTC",
          "autoRenew": false
        }
      },
      {
        "type": "consumer",
        "value": "user-12345",
        "details": {
          "email": "user@example.com",
          "name": "Dexter Morgan",
          "address": { 
              "line1": "123 Main St",
              "line2": "Apt 4B",
              "line3": "",
              "city": "New York",
              "postalCode": "10001",
              "stateCode": "NY",
              "countryCode": "US"
            }
          }
        }
      }
    ]
  }'

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`	Currently only supports “virtual-card”.
`paymentMethodId`	true	string	`null`	The payment method ID (UUID) to create credentials from.
`mandates`	false	Mandate Object[]	`[]`	Array of spending limits and restrictions for the credential.

Mandate Object

Property	Required	Type	Description
`type`	true	string	The mandate type (see supported types below).
`value`	true	string	The mandate value (format varies by type).
`details`	conditional	object	Additional details for the mandate (varies by type).
`metadata`	false	object	Optional metadata for the 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",
  "paymentMethodId": "26859380-7829-4ee1-8a0a-38927881e7ef",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "mandates": [
    {
      "type": "maxAmount",
      "value": "100.00",
      "details": {
        "currency": "840",
        "period": "transaction"
      }
    }
  ]
}

Response Properties

Property	Type	Description
`id`	string	Unique purchase intent identifier (UUID).
`entityId`	string	User ID that owns this purchase intent.
`credentialType`	string	Type of credential created (currently only “virtual-card”).
`status`	string	Purchase intent status (“active”, “verify”, “pending”).
`createdAt`	string	ISO 8601 timestamp when the purchase intent was created.
`expiresAt`	string	ISO 8601 timestamp when the credentials expire (typically 24 hours).
`paymentMethodId`	string	The payment method ID used for this purchase intent.
`projectId`	string	The project ID this purchase intent belongs to.
`mandates`	Mandate Array	The mandates applied to this purchase intent.
`card`	Card Object	Virtual card details (only included for verified Visa/Mastercard intents).

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.

Error Handling

{
  "error": {
    "status": 400,
    "type": "validation_error",
    "title": "Validation failed",
    "message": "The request contained invalid data.",
    "details": {
      "fields": {
        "credentialType": "Credential type must be: virtual-card (other types not currently supported)",
        "paymentMethodId": "Payment method ID must be a valid UUID.",
        "mandates.0.value": "maxAmount value must be a valid decimal amount (e.g., \"100.00\")",
      }
    }
  }
}

Credential Types

Available Credential Types

Type	Description	Status Scenarios
`virtual-card`	Generates a virtual card number for one-time use	`active`, `verify`, `pending`

Note: Only virtual-card is currently supported. Additional credential types may be added in the future.

Status Meanings

Status	Description
`active`	Credential is ready for immediate use
`verify`	Additional verification required before use (Visa/Mastercard 3DS)
`pending`	Credential creation is in progress

Mandate Types

All mandate types are optional. If no mandates are provided, the purchase intent will be created with default restrictions.

Available Mandate Types

Type	Required	Value Format	Details Schema	Description	Notes
`maxAmount`	✅	Decimal string (e.g. “100.00”)	`{ currency: string (ISO 4217 numeric), period?: 'transaction'\|'daily'\|'monthly'\|'yearly' }`	Maximum transaction amount limit	Only one per purchase intent
`expirationTime`		ISO 8601 datetime string	`{ timezone?: string, autoRenew?: boolean }`	Credential expiration date/time	Only one per purchase intent
`merchant`		Merchant name string	`{ category: string, categoryCode: string (4-digit) }`	Specific merchant restriction	Only one per purchase intent
`description`		Description string	Optional object	Purchase description/memo	Only one per purchase intent
`prompt`		Prompt message string	Optional object	User prompt message	Only one per purchase intent
`consumer`	✅	Consumer ID string (UUID auto-generated if empty)	`{ email: string (valid email), address: { line1, line2, line3, city, postalCode, stateCode, countryCode } }`	Consumer identification	Only one per purchase intent

Business Rules

Only one mandate of each type allowed per purchase intent
Currency in maxAmount must be ISO 4217 numeric code (e.g., “840” for USD)
Merchant category codes must be exactly 4 digits

Example Mandates

{
  "mandates": [
    {
      "type": "maxAmount",
      "value": "500.00",
      "details": {
        "currency": "840",
        "period": "transaction"
      }
    },
    {
      "type": "expirationTime", 
      "value": "2024-12-31T23:59:59Z",
      "details": {
        "timezone": "UTC",
        "autoRenew": false
      }
    },
    {
      "type": "merchant",
      "value": "Target",
      "details": {
        "category": "Department Store",
        "categoryCode": "5311"
      }
    },
    {
      "type": "description",
      "value": "Monthly subscription payment"
    },
    {
      "type": "prompt",
      "value": "Authorize payment for Premium subscription?"
    },
    {
      "type": "consumer",
      "value": "user-12345",
      "details": {
        "email": "user@example.com"
      }
    }
  ]
}