On This Page

{#jumplink-list}  
[Markdown](/docs/vas/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-initiate-intro.md)  
Filter  
FILTER BY TAG

pilot

Initiate a Purchase Intent {#intelligent-commerce-purchase-initiate-intro}
==========================================================================

When the customer uses your agents to submit a purchase intent, your agents send an *initiate a purchase intent* request. This request enables `Visa Acceptance Platform` to verify that your agent is acting in accordance with the customer's intent.  
After your agents initiate a purchase intent, you must save the instruction ID in the instructionId response field in your system. The instruction ID is needed to complete follow-on API requests, such as updating and cancelling the purchase intent.

Endpoints
---------

Send a POST request to one of these endpoints:  
**Production:** `POST ``https://api.visaacceptance.com``/acp/v1/instructions`  
**Test:** `POST ``https://apitest.visaacceptance.com``/acp/v1/instructions`

Required Fields for Initiating a Purchase Intent {#intelligent-commerce-purchase-initiate-req-fields}
=====================================================================================================

assuranceData\[\].verificationMethod
:

assuranceData\[\].verificationResults
:

assuranceData\[\].verificationTimestamp
:

clientCorrelationId
:

deviceInformation.applicationName
:

deviceInformation.deviceData.brand
:

deviceInformation.deviceData.type
:

deviceInformation.fingerprintSessionId
:

deviceInformation.ipAddress
:

mandates\[\].declineThreshold.amount
:

mandates\[\].declineThreshold.currencyCode
:

mandates\[\].description
:

mandates\[\].effectiveUntilTime
:

mandates\[\].mandateId
:

paymentInformation.customer.id
:

paymentInformation.instrumentIdentifier.id
:

paymentInformation.paymentInstrument.id
:

tokenizedCard.number
:

Additional Information
----------------------

For complete descriptions of the request fields, see the [Initiate a purchase intent](https://apihub.visa.com/cybs/internal/Spec-Branches/DOCRSTAPI_1374_acp_api_spec/acp_rest.md#operation/initiatePurchaseIntent "") section in the `Intelligent Commerce` API Hub.

Optional Fields for Initiating a Purchase Intent {#intelligent-commerce-purchase-initiate-opt-fields}
=====================================================================================================

assuranceData\[\].additionalData
:

assuranceData\[\].authenticatedIdentities.data
:

assuranceData\[\].authenticatedIdentities.id
:

assuranceData\[\].authenticatedIdentities.provider
:

assuranceData\[\].authenticationContext.action
:

assuranceData\[\].verificationEntity
:

assuranceData\[\].verificationEvents
:

assuranceData\[\].verificationType
:

buyerInformation.merchantCustomerId
:

consumerPrompt
:

deviceInformation.clientDeviceId
:

deviceInformation.deviceData.manufacturer
:

deviceInformation.deviceData.model
:

mandates\[\].preferredMerchantName
:

mandates\[\].quantity
:

recurringPaymentInformation.occurrence
:

Example: Initiating a Purchase Intent {#intelligent-commerce-purchase-initiate-ex-rest}
=======================================================================================

Request

```
{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "paymentInformation": {
    "customer": {
      "id": ""
    },
    "paymentInstrument": {
      "id": ""
    },
    "instrumentIdentifier": {
      "id": "7019989999909760770"
    }
  },
  "deviceInformation": {
    "applicationName": "My Magic App ",
    "fingerprintSessionId": "e48ac10b-58cc-4372-a567-0e02b2c3d489",
    "deviceData": {
      "type": "Mobile",
      "manufacturer": "Apple",
      "brand": "Apple",
      "model": "iPhone 16 Pro Max"
    },
    "ipAddress": "192.168.0.100",
    "clientDeviceId": "c48ac10b-58cc-4372-a567-0e02b2c3d489"
  },
  "tokenizedCard": {
    "number": "15602cf86c70b8b63297134292ec5801"
  },
  "assuranceData": [
    {
      "verificationType": "DEVICE",
      "verificationEntity": "10",
      "verificationEvents": [],
      "verificationMethod": "02",
      "verificationResults": "01",
      "verificationTimestamp": "1735690745",
      "authenticationContext": {
        "action": "AUTHENTICATE"
      },
      "authenticatedIdentities": {
        "data": "authenticatedData",
        "provider": "provider",
        "id": "f48ac10b-58cc-4372-a567-0e02b2c3d489"
      },
      "additionalData": ""
    }
  ],
  "mandates": [
    {
      "mandateId": "d48ac10b-58cc-4372-a567-0e02b2c3d489",
      "preferredMerchantName": "",
      "declineThreshold": {
        "amount": "10000.00",
        "currencyCode": "USD"
      },
      "effectiveUntilTime": "1784841600",
      "quantity": null,
      "description": "description"
    }
  ],
  "recurringPaymentInformation": {
    "occurrence": "WEEKLY"
  },
  "buyerInformation": {
    "merchantCustomerId": "example-customer-id"
  },
  "consumerPrompt": "Authorize payment to Best Buy"
}
```

Response to a Successful Request

```
{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "instructionId": "1-5C8B7367EC00c229ec8a-c96c-a932-a1f3-1faa8f138b01"
}
```

**Follow-On Requests** {#intelligent-commerce-purchase-initiate-followon}
=========================================================================

After the purchase intent is initiated, your agents can send these follow-on requests using the instruction ID from the response message.

**Update a Purchase**
:
Your agent can update the initial purchase intent when the customer changes their purchase inquiry. For more information, see [Update a Purchase Intent](/docs/vas/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-update-intro.md "").

**Cancel a Purchase**
:
Your agent can cancel a purchase intent when the customer chooses to not make the purchase. For more information, see [Cancel a Purchase Intent](/docs/vas/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-purchase-cancel-intro.md "").

**Retrieve Payment Credentials**
:
Your agent can retrieve a customer's payment credentials for a fast checkout experience. For more information, see [Retrieve Payment Credentials](/docs/vas/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-retrieve-credentials-intro.md "").
:
A customer's credentials are retrievable only when the customer has enrolled their payment information and chosen a purchase intent option.

**Confirm Transaction Events**
:
Your agent can verify when a purchase is complete and display a payment confirmation to the customer. For more information, see [Confirm Transaction Events](/docs/vas/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-confirm-trxn-intro.md "").  
RELATED TO THIS PAGE