# Identity transaction eligibility

Request transaction eligibility for a specific identity

Endpoint: POST /eapi/v0/identities/transactions/eligibility
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `identityReference` (string)
    Partner identity reference.
    Example: user-123

  - `method` (string, required)
    The payment method.
| Available payments |
|  --- |
| debit-credit-card |
| apple-pay |
| sepa-bank-transfer |
| gbp-bank-transfer |
| ach-bank-transfer |
| zar-bank-transfer |
| interac-bank-transfer |
| ideal-bank-transfer |
| google-pay |
| payid-bank-transfer |
| wire-transfer |
| spei |
| pse |
| khipu |
| aud-bank-transfer |
| usd-bank-transfer |
    Example: payid-bank-transfer

  - `transactionType` (string, required)
    Transaction type. Must be a valid value of `TransactionTypeEnum`.
(Populate the allowed values here if you want strict client validation.)
    Enum: "ONRAMP", "OFFRAMP"

  - `fiat` (string, required)
    Fiat currency code allowed for the partner (e.g., ISO 4217).
Enforced server-side validation for availbility
    Example: AUD

  - `crypto` (string, required)
    Crypto asset code. Enforced server-side validation for availbility
    Example: BTC

  - `fiatAmount` (string)
    Fiat amount as a decimal string.
Mutually exclusive with `cryptoAmount`.
    Example: 250.00

  - `cryptoAmount` (string)
    Crypto amount as a decimal string.
Mutually exclusive with `fiatAmount`.
    Example: 0.125

  - `blockchain` (string, required)
    Blockchain identifier.
    Example: BITCOIN

  - `email` (string)
    Required when `identityReference` is not provided.
    Example: user@example.com

  - `countryOfResidence` (string)
    Required when `identityReference` is not provided.
ISO 3166-1 alpha-2 country code.
    Example: AU

  - `dateOfBirth` (string)
    Optional when `identityReference` is not provided. (Format YYYY-MM-DD)"
    Example: 1990-01-30

  - `state` (string)
    Required if `countryOfResidence` is `US`. (Enforced server-side.)
    Example: CA

## Request examples:

  - `Check eligibility with identity reference` (unknown)
    Check if existing customer can perform transaction

  - `Check eligibility without identity reference` (unknown)
    Check eligibility for new customer using personal details

## Response 202:

  - `202` (unknown)
    Eligibility check result

## Response 202 fields (application/json):

  - `paymentReady` (boolean, required)
    Whether the identity is eligible and can proceed with payment/transaction. When true, there are no KYC requirements.
    Example: false

  - `kycRequirements` (array, required)
    List of outstanding requirements that must be satisfied before payment can proceed.
If `paymentReady` is true, this will typically be an empty array.
    Example: ["TIN","NAME","DOB","ADDRESS","POA","DOCUMENT","SELFIE","SOURCE_FUNDS","OCCUPATION","PURPOSE_OF_TX"]

## Response 400:

  - `400` (unknown)
    Bad request due to invalid input.
**Common Causes**:
- Malformed JSON in request body
- Invalid data types
- Missing required fields
- Invalid request structure

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Bad Request

  - `code` (integer)
    HTTP status code
    Example: 400

  - `traceId` (string)
    Unique identifier for this error instance. Use this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 404:

  - `404` (unknown)
    The requested resource was not found.
**Common Causes**:
- Invalid ramp ID
- Invalid identity reference
- Resource has been deleted
- Incorrect endpoint URL

## Response 404 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Not Found

  - `code` (integer)
    Error code (may be HTTP status or custom code)
    Example: 500100

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 422:

  - `422` (unknown)
    Validation error - request is well-formed but contains invalid data.
**Common Causes**:
- Field validation failures
- Business rule violations
- Invalid field combinations
- Out of range values

## Response 422 fields (application/json):

  - `message` (string)
    Summary of validation errors
    Example: The given data was invalid.

  - `errors` (object)
    Map of field names to error messages.
**Format**: Each key is a field name, value is an array of error messages for that field.
    Example: {"email":["The email field is required."],"fiatAmount":["The fiat amount must be at least 10."]}

  - `code` (integer)
    HTTP status code
    Example: 422

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 202 examples:

  - `Customer ready to transact` (unknown)
    Customer has completed all KYC requirements and can proceed

  - `KYC requirements needed` (unknown)
    Customer needs to complete KYC verification

  - `Additional information required` (unknown)
    Customer needs to provide occupation and source of funds

  - `Tax ID required` (unknown)
    Customer needs to provide tax identification