Create Purchase Intent

Create a Purchase Intent to retrieve a credential (virtual card, network token, etc) enabling a purchase to be completed on behalf of the consumer.

Request

curl -X POST \
  https://api.basistheory.ai/tenants/your-tenant-id/purchase-intent \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "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
`tenantId`	true	string	`null`	The tenant ID.

Request Parameters

Parameter	Required	Type	Default	Description
`credentialType`	true	string	`null`	The type of credential to create from payment method.
`paymentMethodId`	true	string	`null`	The payment method ID.
`mandates`	true	Mandate Object[]	`null`	Array of mandate objects for allowing credential use.

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": "94c94330-94fd-4832-a106-e8474a274fe4",
  "credentialType": "virtual-card",
  "status": "active",
  "card": {
    "number": "2222030198005808",
    "expirationMonth": "07",
    "expirationYear": "2028",
    "cvc": "211"
  },
  "createdAt": "2025-06-16T14:00:00Z",
  "expiresAt": "2025-06-13T18:42:01Z"
}

Response Properties

Property	Type	Description
`id`	string	The purchase intent id.
`entityId`	string	The ID for the entity that owns the purchase intent.
`credentialType`	string	The purchase intent credential type.
`status`	string	The purchase intent status: `active`, `verify` or `unavailable`.
`card`	Card Object	Details for a `"virtual-card"` type credential.
`token`	Token Object	Details for a `"network-token"` type credential.
`createdAt`	datetime	The purchase intent credential created date.
`expiresAt`	datetime	The purchase intent expiration date for the credential.

Virtual Card Object

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

Token Object

Property	Type	Description
`number`	string	The token number.
`expirationMonth`	string	Token expiration month in `MM` format.
`expirationYear`	string	Token expiration year in `YYYY` format.
`cryptogram`	string	The token cryptogram.

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
      }
    }
  ]
}