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:

Webhook Notification

To receive real-time asynchronous updates when a verification is successful, you must configure a webhook URL in your Xendit Dashboard 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"
  }
}