---
title: "Card verification"
slug: "card-verification"
updated: 2026-07-08T03:26:12Z
published: 2026-07-08T03:26:12Z
canonical: "docs.xendit.co/card-verification"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xendit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Card verification

## Payment Method Verification (`VERIFY_PAYMENT_METHOD`)

### Purpose

Allows merchants to verify and vault a customer's card details without charging them (e.g., during recurring subscription setup or user onboarding). Xendit automatically abstracts processor-specific mechanics, such as native $0 authorizations or automatic micro-charge voids behind a single, clean interface.

### Key Characteristics

- **No Amount Required:** `request_amount` and `capture_method` are ignored if passed.
- **No Charge Lifecycle:** Because no funds are moved, this request cannot be captured, canceled, or refunded.
- **New Terminal State:** Reaches a final status of `VERIFIED` upon success.

---

## Create a Payment Method Verification

### Endpoint

POST request - ` /v3/payment_requests`

### Required Fields for Verification

- `type`: Must be set to `VERIFY_PAYMENT_METHOD`.
- `channel_code`: Must be set to `CARDS` (currently supported channel).
- `channel_properties.card_details`: Full card PAN details are required.

### Request Sample

POST request - `/v3/payment_requests`

```
{
  "reference_id": "verify_card_cust_789",
  "type": "VERIFY_PAYMENT_METHOD",
  "country": "SG",
  "currency": "SGD",
  "customer_id": "cust-12515215",
  "channel_code": "CARDS",
  "channel_properties": {
    "card_details": {
      "card_number": "4000000000001091",
      "cvn": "123",
      "expiry_month": "09",
      "expiry_year": "2027",
      "cardholder_first_name": "Shopper",
      "cardholder_last_name": "The hopper",
      "cardholder_email": "shopper@example.com",
      "cardholder_phone_number": "+65123456789"
    },
    "card_on_file_type": "MERCHANT_UNSCHEDULED",
    "success_return_url": "[https://merchant.co/verify/success](https://merchant.co/verify/success)",
    "failure_return_url": "[https://merchant.co/verify/failure](https://merchant.co/verify/failure)",
    "skip_three_ds": true
  },
  "description": "Card verification — no charge"
}
```

### Response Sample

If the card requires 3D Secure (3DS) validation, the request returns a `REQUIRES_ACTION` status alongside a redirect URL. Otherwise, it returns `VERIFIED` immediately.

POST response - `/v3/payment_requests`

```
{
   "payment_request_id": "pr-aa974469-8be9-8527-831a-f363fd8bddcd",
   "status": "VERIFIED",
   "type": "VERIFY_PAYMENT_METHOD",
   "channel_code": "CARDS",
   "business_id": "69xxxxxx62cfa43",
   "country": "SG",
   "reference_id": "verify_card_cust_789",
   "currency": "SGD",
   "capture_method": "MANUAL",
   "request_amount": 0,
   "created": "2026-07-08T02:18:09.076Z",
   "updated": "2026-07-08T02:18:09.087Z",
   "channel_properties": {
       "card_details": {
           "masked_card_number": "400000XXXXXX1091",
           "expiry_month": "09",
           "expiry_year": "2027",
           "fingerprint": "6320100aea3d99001aad04b7",
           "type": "CREDIT",
           "network": "VISA",
           "country": "ID",
           "issuer": "BRI",
           "cardholder_first_name": "Budi",
           "cardholder_last_name": "Santoso",
           "cardholder_email": "budi@example.com",
           "cardholder_phone_number": "+628123456789"
       },
       "success_return_url": "[https://merchant.co/verify/success](https://merchant.co/verify/success)",
       "failure_return_url": "[https://merchant.co/verify/failure](https://merchant.co/verify/failure)",
       "skip_three_ds": true
   },
   "description": "Card verification — no charge",
   "latest_payment_id": "py-aa974469-8be9-8527-831a-f363fd8bddcd",
   "actions": []
}
```

---

## Status Lifecycle

Verification requests move through the following states:

| Status | Terminal State? | Description |
| --- | --- | --- |
| `PENDING` | No | Request created; awaiting upstream processor response. |
| `REQUIRES_ACTION` | No | 3DS challenge required; cardholder must complete authentication. |
| `VERIFIED` | Yes (Success) | Card authenticated and vaulted successfully. No further actions allowed. |
| `FAILED` | Yes (Failure) | Verification failed due to 3DS failure or issuer decline. |

---

## Webhook Notification

To receive real-time asynchronous updates when a verification is successful, you must configure a [webhook](/v1/docs/webhook-events) URL in your [Xendit Dashboard](https://dashboard.xendit.co/) to listen for the verification event.

When a payment request successfully completes authentication and vaults, Xendit triggers the `payment.verified` event.

### Event Name

`payment.verified`

### Event Name

`payment.verified`

### Webhook Payload Sample

```
{
  "event": "payment.verified",
  "business_id": "5f27a14axxxxx",
  "created": "2026-07-30T10:05:22Z",
  "data": {
    "id": "pr-abc123xyz",
    "reference_id": "verify_card_cust_789",
    "type": "VERIFY_PAYMENT_METHOD",
    "status": "VERIFIED",
    "country": "SG",
    "currency": "SGD",
    "customer_id": "cust-abc123",
    "channel_code": "CARDS",
    "metadata": {},
    "created": "2026-04-30T10:00:00Z",
    "updated": "2026-04-30T10:05:22Z"
  }
}
```