> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/payments/payment-method-verification.md).

# Verifying a Payment Method

Use the verification endpoint when you want to validate a card, token, or network token without running a normal purchase flow.

## Overview

Route:

```
POST /v1/payments/verify
```

Authentication:

```
Authorization: Basic base64(clientId:apiKey)
```

The verification flow authorizes a small amount and then requests a cancellation. Use it for card validation, subscription setup, or checking that a stored payment method is still usable.

## Request shape

```json
{
  "merchantId": 12345,
  "referenceId": "verify-1001",
  "invoiceNumber": "verify-1001",
  "amount": {
    "currency": "USD"
  },
  "paymentMethod": {
    "source": "card",
    "card": {
      "number": "4111111111111111",
      "expMonth": 12,
      "expYear": 2028,
      "cvc": "123",
      "cardholder": {
        "firstName": "Test",
        "lastName": "User",
        "email": "test.user@example.com"
      }
    }
  },
  "browserDetails": {
    "ipAddress": "203.0.113.10",
    "userAgent": "Mozilla/5.0"
  },
  "metadata": {
    "purpose": "subscription-setup"
  }
}
```

### Important request notes

* `merchantId` and `referenceId` are required.
* `amount` only takes `currency` in this request model.
* `paymentMethod` supports the same public sources used by the payment APIs, including card, token, and network-token inputs.
* `browserDetails` should be included for browser-based card-not-present flows, especially when 3DS may be required.

## Verification amount behavior

The current backend sets the internal verification amount from the currency:

* `USD` uses `1`
* `UYU` uses `25`

You do not send a `total` field in the verification request.

## Example request

```bash
curl --request POST \
  --url https://api.testing.plexo.com.uy/v1/payments/verify \
  --header "Authorization: Basic <base64(clientId:apiKey)>" \
  --header "Content-Type: application/json" \
  --data '{
    "merchantId": 12345,
    "referenceId": "verify-1001",
    "invoiceNumber": "verify-1001",
    "amount": {
      "currency": "USD"
    },
    "paymentMethod": {
      "source": "card",
      "card": {
        "number": "4111111111111111",
        "expMonth": 12,
        "expYear": 2028,
        "cvc": "123",
        "cardholder": {
          "firstName": "Test",
          "lastName": "User",
          "email": "test.user@example.com"
        }
      }
    },
    "browserDetails": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    }
  }'
```

## Response shape

The endpoint returns a `PaymentDto` when the verification flow succeeds.

```json
{
  "id": "550e8400e29b41d4a716446655440000",
  "referenceId": "verify-1001",
  "status": "authorized",
  "amount": {
    "total": 1,
    "currency": "USD"
  },
  "transactions": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "type": "authorization",
      "status": "approved"
    }
  ]
}
```

Treat the endpoint as a verification flow rather than a settled payment flow. The backend performs the authorization and then triggers a cancellation request.

If customer interaction is required, inspect the returned `actions` array the same way you would for a normal payment.

## Common outcomes

| Status code | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `200`       | The payment method passed the verification flow.                                           |
| `400`       | The request is invalid, the merchant is unavailable, or verification could not be created. |
| `401`       | Authentication failed.                                                                     |
| `403`       | The authenticated client cannot use that merchant.                                         |
| `422`       | The payment method was declined or a processor-side verification step failed.              |

## Related resources

* [Authentication](/rest-api/getting-started/authentication.md)
* [Payment Processing](/rest-api/payments/payment-processing.md)
* [Payment and Transaction Lifecycle](/rest-api/core-concepts/transaction-lifecycle.md)
* [Error Codes Reference](/rest-api/reference/error-codes.md)