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

# POST /v1/transactions/verify — Verify Payment Details

> POST /v1/transactions/verify — confirm that payment method details are valid and not associated with known fraud before processing a charge.

Use this endpoint to validate payment method details before you initiate a charge — without triggering a full risk scoring pass. FraudEG checks the payment method against BIN databases, velocity windows, and fraud blacklists, then returns a per-check breakdown so you can gate pre-authorization flows without unnecessary friction for legitimate users.

## Endpoint

```http theme={null}
POST https://api.fraudeg.com/v1/transactions/verify
```

## Request Headers

| Header          | Value              | Required |
| --------------- | ------------------ | -------- |
| `Authorization` | `Bearer <API_KEY>` | Yes      |
| `Content-Type`  | `application/json` | Yes      |

## Request Body

<ParamField body="payment_method" type="object" required>
  The payment method details you want to verify.

  <Expandable title="payment_method fields">
    <ParamField body="type" type="string" required>
      Payment method type. Accepted values: `card`, `bank_account`, `wallet`.
    </ParamField>

    <ParamField body="card_bin" type="string">
      Card BIN (first 6–8 digits). Required for `card` type to run BIN-level checks.
    </ParamField>

    <ParamField body="last_four" type="string">
      Last four digits of the card number. Used for velocity and blacklist matching.
    </ParamField>

    <ParamField body="bank_account_number" type="string">
      Masked bank account number for `bank_account` type (e.g., `"****4321"`). Never send the full account number.
    </ParamField>

    <ParamField body="routing_number" type="string">
      Bank routing number. Used to verify the institution and check for known fraudulent routing numbers.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="user_id" type="string" required>
  Your internal user ID. FraudEG uses this to run user-level velocity checks against recent payment activity.
</ParamField>

<ParamField body="amount" type="integer">
  Intended transaction amount in the smallest currency unit (e.g., `14900` for \$149.00 USD). Providing this value enables amount-aware velocity checks and flags unusual purchase sizes for this user's history.
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code for the intended transaction (e.g., `"USD"`, `"EUR"`, `"GBP"`). Required when `amount` is provided so FraudEG can apply currency-appropriate thresholds in velocity and amount checks.
</ParamField>

## Response Fields

<ResponseField name="verification_id" type="string">
  Unique identifier for this verification record. Store this alongside your pre-authorization record for audit purposes.
</ResponseField>

<ResponseField name="status" type="string">
  Overall verification outcome. One of:

  * `valid` — All checks passed; the payment method appears legitimate.
  * `suspicious` — One or more checks returned a warning; consider step-up verification.
  * `invalid` — One or more checks failed; decline or request a different payment method.
</ResponseField>

<ResponseField name="checks" type="array">
  Ordered list of individual checks performed, with per-check results.

  <Expandable title="check object fields">
    <ResponseField name="name" type="string">
      Check identifier. Possible values include `bin_check`, `velocity_check`, `blacklist_check`, `routing_check`, and `account_age_check`.
    </ResponseField>

    <ResponseField name="result" type="string">
      Outcome of this individual check. One of `pass`, `warn`, or `fail`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the verification was performed (e.g., `"2024-11-15T10:45:00Z"`).
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.fraudeg.com/v1/transactions/verify \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "payment_method": {
        "type": "card",
        "card_bin": "520082",
        "last_four": "1234"
      },
      "user_id": "usr_8f3kd92",
      "amount": 14900,
      "currency": "USD"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.fraudeg.com/v1/transactions/verify', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      payment_method: {
        type: 'card',
        card_bin: '520082',
        last_four: '1234',
      },
      user_id: 'usr_8f3kd92',
      amount: 14900,
      currency: 'USD',
    }),
  });

  const data = await response.json();
  console.log(data);
  // {
  //   verification_id: 'ver_5pRx2mN8qT',
  //   status: 'valid',
  //   checks: [
  //     { name: 'bin_check', result: 'pass' },
  //     { name: 'velocity_check', result: 'pass' },
  //     { name: 'blacklist_check', result: 'pass' }
  //   ],
  //   created_at: '2024-11-15T10:45:00Z'
  // }
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "verification_id": "ver_5pRx2mN8qT",
  "status": "valid",
  "checks": [
    { "name": "bin_check", "result": "pass" },
    { "name": "velocity_check", "result": "pass" },
    { "name": "blacklist_check", "result": "pass" }
  ],
  "created_at": "2024-11-15T10:45:00Z"
}
```

<Tip>
  For high-value transactions, combine this endpoint with `POST /v1/transactions/score` for layered protection. Run `/verify` first during payment method collection to catch obviously invalid instruments early, then call `/score` at the point of purchase to apply the full ML-powered risk model with device and behavioral signals.
</Tip>