# Card transaction

Process an online card transaction.

## Initiate a card transaction

/v1/transactions

### Request examples

Without CVC
Use the following request to initiate a card transaction without CVC.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "ECOM_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "amounts": {
    "transaction": 20,
    "currencyCode": "GBP",
    "gratuity": 0
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "01",
      "expiryYear": "2025",
      "holderName": "John Doe"
    }
  }
}
```

| 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 doesn't require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `amounts.gratuity`number | The gratuity or tip amount added by the customer to the transaction total. This field can't be used together with `serviceCharge`. |
| `amounts.serviceCharge`object | Details about the service charge applied to the transaction. This field can't be used together with `gratuity`. |
| `amounts.serviceCharge.amount`number | The service charge amount. |
| `amounts.serviceCharge.percentage`number | The service charge percentage. |
| `amounts.serviceCharge.optional`boolean | Whether the service charge is optional. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.primaryAccountNumber`string (10-19 characters) | The unique number assigned to a payment card, such as a credit or debit card. This number typically contains 16 digits, structured in a specific format to indicate the card network, issuing bank, and account number. |
| `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.holderName`string (≤ 100 characters) | The full name of the individual who owns the payment card. This name is printed on the physical card and is used for verifying the cardholder's identity during transactions. |


With CVC
Use the following request to initiate a card transaction with CVC.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "ECOM_001",
  "merchantTransactionDate": "2025-01-27 08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "amounts": {
    "transaction": 1,
    "currencyCode": "EUR",
    "gratuity": 0
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "02",
      "expiryYear": "2030",
      "holderName": "John Doe",
      "cardVerificationCode": "240"
    }
  }
}
```

| 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 doesn't require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `amounts.`number | The  or tip amount added by the customer to the transaction total. This field can't be used together with `serviceCharge`. |
| `amounts.serviceCharge`object | Details about the service charge applied to the transaction. This field can't be used together with ``. |
| `amounts.serviceCharge.amount`number | The service charge amount. |
| `amounts.serviceCharge.percentage`number | The service charge percentage. |
| `amounts.serviceCharge.optional`boolean | Whether the service charge is optional. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Details about the card. |
| `fundingData.card.primaryAccountNumber`string (10-19 characters) | The unique number assigned to a payment card, such as a credit or debit card. This number typically contains 16 digits, structured in a specific format to indicate the card network, issuing bank, and account number. |
| `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.holderName`string (≤ 100 characters) | The full name of the individual who owns the payment card. This name is printed on the physical card and is used for verifying the cardholder's identity during transactions. |
| `fundingData.card.cardVerificationCode`string (3 to 4 characters) | The Card Verification Code (CVC) associated with the payment card, used to verify that the cardholder is in possession of the card during non-face-to-face transactions. |


### Response examples

Without CVC
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": {},
  "approvalCode": "849535",
  "merchantTransactionDate": "2025-03-31T12:25:31",
  "merchantTransactionId": "9e6fa686-2a79-4813-8d1c-be9be7f1212b",
  "systemTransactionId": "89e2e55c-fcfa-4e35-97ea-3ab7de45619c",
  "fundingData": {
    "cardScheme": "MasterCard",
    "expiryMonth": null,
    "expiryYear": null,
    "gatewayTokenId": "5fbd77ce-02c1-40ed-94bc-1016660b7512",
    "nameVerificationResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "pxpfinancial",
      "code": "00",
      "emvDataResponse": {},
      "paymentAccountReference": "637607302178175469",
      "electronicCommerceIndicatorAdjustment": "07",
      "merchantAdvice": {},
      "authorisedAmount": 20,
      "settlementDate": "2025-04-01T00:00:00"
    },
    "processorTransactionId": "6ac50290-3211-4359-9651-843305bc315f"
  }
}
```

With CVC
If your request is successful, you'll receive a `200` response and a Transaction (Card Authorised) webhook notification.

The response includes the transaction's updated `state`, as well as two `cardVerificationCodeResult` fields indicating the result of the CVV check. The first one comes from the PXP Unity Gateway and ddescribes the outcome of the check in a human-readable format, while the second one is the raw data received from the provider.

The possible CVC check results are:

* `NoInformationAvailable `: The CVC wasn't provided by the shopper.
* `CardSecurityCodeMatched`: The CVC provided matched the data held on the card issuer's system.
* `CardSecurityCodeNotMatched `: The CVC provided didn't match the data held by the card issuer's system.
* `CardSecurityCodeNotChecked`: The CVC wasn't checked. For example, because the card issuer doesn't support CVC checks or the service was temporarily unavailable.


If the check failed, you can look at the `merchantAdvice.message` for advice on your next steps.

```json
{
  "state": "Approved",
  "stateData": {},
  "merchantTransactionDate": "2025-04-02T17:02:02",
  "merchantTransactionId": "145a395d-813d-45a3-a6b9-7fcdf1db6c03",
  "systemTransactionId": "0380dfc4-77ef-4653-998a-3fa525d6e404",
  "fundingData": {
    "cardScheme": "Visa",
    "expiryMonth": null,
    "expiryYear": null,
    "gatewayTokenId": "c78ee1e1-6d5c-4338-9336-e929d8e76acc",
    "cardVerificationCodeResult": "CardSecurityCodeNotMatched", // CVC check result from the PXP Unity Gateway
    "nameVerificationResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "pxpfinancial",
      "code": "91",
      "cardVerificationCodeResult": "03", // CVC check result from the provider
      "emvDataResponse": {},
      "schemeTransactionId": "305092613241176",
      "schemeTransactionLinkId": "TX1234567890123456",
      "electronicCommerceIndicatorAdjustment": "07",
      "merchantAdvice": {
        "code": "02",
        "message": "Try again later"
      },
      "authorisedAmount": 0
    },
    "processorTransactionId": "9009e0bc-a082-412f-a8b9-b1f3317e4e2a"
  }
}
```