# Token transaction

Process an online transaction using a scheme token or gateway token.

## Initiate a token transaction

/v1/transactions

### Request examples

Scheme token number with cryptogram
Use the following request to initiate a scheme token number transaction with a token cryptogram.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "schemeTokenNumber": "4837261112345678",
      "expiryMonth": "03",
      "expiryYear": "2027",
      "schemeTokenCryptogram": "AAEBAwQjSQAAXXXXXXXJYe0BbQA="
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "threeDSecureData": {
    "cardHolderAuthenticationVerificationValue": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
    "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
    "electronicCommerceIndicator": "07",
    "threeDSecureVersion": "2.1.0"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents). Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.schemeTokenNumber`string | A scheme token issued by Visa or Mastercard, used for subsequent transaction processing. This token enhances security and facilitates recurring transactions, providing a secure and efficient alternative to sharing sensitive card details. |
| `fundingData.card.expiryMonth`string (2 characters) | The expiry month (`MM`) of the card. |
| `fundingData.card.expiryYear`string (4 characters) | The expiry year (`YYYY`) of the card. |
| `fundingData.card.schemeTokenCryptogram`string | A unique cryptogram generated during the tokenisation process, used to enhance the security of transaction processing. This cryptogram acts as a secure and unique identifier, akin to the token authentication verification value (TAVV), ensuring that each transaction is authenticated and verified without directly using sensitive card details. It plays a crucial role in the secure electronic payment ecosystem, especially in tokenised transactions, by providing an additional layer of security and authentication. |
| `threeDSecureData`object | Details about the 3DS data. If `authenticationId` is provided, it will be used by PXP to look up the associated 3D Secure authentication data. If `authenticationId` isn't provided, you'll need to provide the authentication data instead. |
| `threeDSecureData.authenticationId`string | A unique reference provided by PXP for the authentication request, represented as a GUID. |
| `threeDSecureData.cardHolderAuthenticationVerificationValue`string | The Cardholder Authentication Verification Value (CAVV) is generated by the card issuer as part of the 3D Secure authentication process for Visa transactions. It indicates that the cardholder has been authenticated, and it should be appended to the authorisation request. |
| `threeDSecureData.directoryServerTransactionId`string | The 3DS 2.0 transaction identifier returned by the card issuer, unique to each authentication attempt. |
| `threeDSecureData.electronicCommerceIndicator`string | The Electronic Commerce Indicator (ECI) specifies the security level of an online transaction and the authentication outcome, crucial for determining liability in the event of a dispute. Possible values:`01`: Transaction processed with SSL or equivalent but without cardholder authentication (considered less secure, higher risk).`02`: Transaction processed with cardholder authentication (e.g., 3D Secure), indicating a higher level of security.`05`: Transaction processed with 3D Secure authentication, cardholder authenticated successfully (high security).`06`: Transaction attempted 3D Secure authentication but could not be completed; cardholder not authenticated (medium security).`07`: Transaction processed without 3D Secure authentication, due to issuer or cardholder not participating in 3D Secure (considered less secure, higher risk). |
| `threeDSecureData.threeDSecureVersion`string | The version of the 3D Secure protocol used for the transaction's authentication, as returned by the Payment Service Provider (PSP)'s 3D Secure service. This indicates the specific set of 3D Secure features and security measures applied. |
| `threeDSecureData.threeDSecureTransactionStatus`string | The status of the transaction after being authenticated using the 3D Secure protocol, as provided by the Payment Service Provider (PSP). This indicates the result of the 3D Secure authentication process. |


Scheme token number without cryptogram
Use the following request to initiate a scheme token number transaction without a token cryptogram.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "schemeTokenNumber": "4837261112345678",
      "expiryMonth": "03",
      "expiryYear": "2027"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "threeDSecureData": {
    "cardHolderAuthenticationVerificationValue": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
    "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
    "electronicCommerceIndicator": "07",
    "threeDSecureVersion": "2.1.0"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents). Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.schemeTokenNumber`string | A scheme token issued by Visa or Mastercard, used for subsequent transaction processing. This token enhances security and facilitates recurring transactions, providing a secure and efficient alternative to sharing sensitive card details. |
| `fundingData.card.expiryMonth`string (2 characters) | The expiry month (`MM`) of the card. |
| `fundingData.card.expiryYear`string (4 characters) | The expiry year (`YYYY`) of the card. |
| `threeDSecureData`object | Details about the 3DS data. If `authenticationId` is provided, it will be used by PXP to look up the associated 3D Secure authentication data. If `authenticationId` isn't provided, you'll need to provide the authentication data instead. |
| `threeDSecureData.authenticationId`string | A unique reference provided by PXP for the authentication request, represented as a GUID. |
| `threeDSecureData.cardHolderAuthenticationVerificationValue`string | The Cardholder Authentication Verification Value (CAVV) is generated by the card issuer as part of the 3D Secure authentication process for Visa transactions. It indicates that the cardholder has been authenticated, and it should be appended to the authorisation request. |
| `threeDSecureData.directoryServerTransactionId`string | The 3DS 2.0 transaction identifier returned by the card issuer, unique to each authentication attempt. |
| `threeDSecureData.electronicCommerceIndicator`string | The Electronic Commerce Indicator (ECI) specifies the security level of an online transaction and the authentication outcome, crucial for determining liability in the event of a dispute. Possible values:`01`: Transaction processed with SSL or equivalent but without cardholder authentication (considered less secure, higher risk).`02`: Transaction processed with cardholder authentication (e.g., 3D Secure), indicating a higher level of security.`05`: Transaction processed with 3D Secure authentication, cardholder authenticated successfully (high security).`06`: Transaction attempted 3D Secure authentication but could not be completed; cardholder not authenticated (medium security).`07`: Transaction processed without 3D Secure authentication, due to issuer or cardholder not participating in 3D Secure (considered less secure, higher risk). |
| `threeDSecureData.threeDSecureVersion`string | The version of the 3D Secure protocol used for the transaction's authentication, as returned by the Payment Service Provider (PSP)'s 3D Secure service. This indicates the specific set of 3D Secure features and security measures applied. |
| `threeDSecureData.threeDSecureTransactionStatus`string | The status of the transaction after being authenticated using the 3D Secure protocol, as provided by the Payment Service Provider (PSP). This indicates the result of the 3D Secure authentication process. |


Scheme token ID
Use the following request to initiate a scheme token ID transaction.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "schemeTokenNumber": "4837261112345678",
      "expiryMonth": "03",
      "expiryYear": "2027"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "threeDSecureData": {
    "cardHolderAuthenticationVerificationValue": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
    "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
    "electronicCommerceIndicator": "07",
    "threeDSecureVersion": "2.1.0"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents). Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.schemeTokenId`string | A scheme token ID issued by Visa or Mastercard, used for subsequent transaction processing. This token enhances security and facilitates recurring transactions, providing a secure and efficient alternative to sharing sensitive card details. |
| `fundingData.card.cardVerificationCode`string (3 to 4 characters) | The Card Verification Code (CVC) associated with the payment card, a security feature for transactions where the card is not physically present. The CVC is typically a 3 or 4 digit number found on the card, used to verify that the cardholder is in possession of the card during non-face-to-face transactions. |
| `threeDSecureData`object | Details about the 3DS data. If `authenticationId` is provided, it will be used by PXP to look up the associated 3D Secure authentication data. If `authenticationId` isn't provided, you'll need to provide the authentication data instead. |
| `threeDSecureData.authenticationId`string | A unique reference provided by PXP for the authentication request, represented as a GUID. |
| `threeDSecureData.cardHolderAuthenticationVerificationValue`string | The Cardholder Authentication Verification Value (CAVV) is generated by the card issuer as part of the 3D Secure authentication process for Visa transactions. It indicates that the cardholder has been authenticated, and it should be appended to the authorisation request. |
| `threeDSecureData.directoryServerTransactionId`string | The 3DS 2.0 transaction identifier returned by the card issuer, unique to each authentication attempt. |
| `threeDSecureData.electronicCommerceIndicator`string | The Electronic Commerce Indicator (ECI) specifies the security level of an online transaction and the authentication outcome, crucial for determining liability in the event of a dispute. Possible values:`01`: Transaction processed with SSL or equivalent but without cardholder authentication (considered less secure, higher risk).`02`: Transaction processed with cardholder authentication (e.g., 3D Secure), indicating a higher level of security.`05`: Transaction processed with 3D Secure authentication, cardholder authenticated successfully (high security).`06`: Transaction attempted 3D Secure authentication but could not be completed; cardholder not authenticated (medium security).`07`: Transaction processed without 3D Secure authentication, due to issuer or cardholder not participating in 3D Secure (considered less secure, higher risk). |
| `threeDSecureData.threeDSecureVersion`string | The version of the 3D Secure protocol used for the transaction's authentication, as returned by the Payment Service Provider (PSP)'s 3D Secure service. This indicates the specific set of 3D Secure features and security measures applied. |
| `threeDSecureData.threeDSecureTransactionStatus`string | The status of the transaction after being authenticated using the 3D Secure protocol, as provided by the Payment Service Provider (PSP). This indicates the result of the 3D Secure authentication process. |


Gateway token
Use the following request to initiate a card transaction using a gateway token ID from a saved card, rather than the full card details.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "gatewayTokenId": "2357e042-2bf0-4886-8d9d-718fa5909761"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents).  Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.gatewayTokenId`string (16 characters) | A securely stored token that corresponds to a previously saved payment card. This token is generated and maintained by PXP to facilitate recurring transactions or transactions using stored card details, ensuring enhanced security and convenience. |


### Response example

Scheme token with cryptogram
If your request is successful, you'll receive a `200` response that includes the transaction's `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "cardVerificationCodeResult": "A",
      "addressVerificationServiceResult": "D",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "retrievalReferenceNumber": "613808317649",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}
```

Scheme token without cryptogram
If your request is successful, you'll receive a `200` response that includes the transaction's `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "cardVerificationCodeResult": "A",
      "addressVerificationServiceResult": "D",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "retrievalReferenceNumber": "613808317649",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}
```

Gateway token
If your request is successful, you'll receive a `200` response that includes the transaction's `state`. You'll also receive a Transaction (Card Authorised) webhook notification.

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "cardVerificationCodeResult": "A",
      "addressVerificationServiceResult": "D",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "retrievalReferenceNumber": "613808317649",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}
```