Create a Payment Instrument

Overview

Create a Payment Instrument for a card, bank account, or using a third-party token. The Payment Instrument resource represents tokenized payment details and must be associated with an Identity.

Important: Direct API creation should only be used for testing. For production environments, use Ahrvo Network hosted fields to ensure PCI compliance.

Resource Access

• User Permissions: All users can access this endpoint
• Endpoint: POST /payment_instruments

Arguments

Common Fields (All Types)

Parameter	Type	Required	Description
type	string	Yes	Type of payment instrument (PAYMENT_CARD, BANK_ACCOUNT, APPLE_PAY, GOOGLE_PAY, TOKEN)
identity	string	Yes	The ID of the Identity to associate with this Payment Instrument
name	string	No	Name on the card or bank account name

Payment Card Fields

Parameter	Type	Required	Description
number	string	Yes	The card number
expiration_month	integer	Yes	Card expiration month (1-12)
expiration_year	integer	Yes	Card expiration year (4 digits)
security_code	string	No	CVV/CVC code
address	object	No	Billing address
account_updater_enabled	boolean	No	Enable automatic card updates (default: false)
network_token_enabled	boolean	No	Enable network tokenization (default: false)

Bank Account Fields

Parameter	Type	Required	Description
account_number	string	Yes	Bank account number
bank_code	string	Yes	Routing/ABA number (USA)
account_type	string	Yes	Account type (CHECKING, SAVINGS, BUSINESS_CHECKING, PERSONAL_CHECKING)
country	string	No	Country code (USA, CAN - default: USA)
currency	string	No	Currency code (default: USD)
institution_number	string	Conditional	Required for Canadian bank accounts
transit_number	string	Conditional	Required for Canadian bank accounts

Digital Wallet/Token Fields

Parameter	Type	Required	Description
third_party_token	string	Yes	Token from third-party service
third_party	string	No	Third-party provider (e.g., PLAID)
merchant_identity	string	Yes	Merchant Identity ID for wallet/token
address	object	No	Billing address

Example Request (Payment Card)

curl -X POST \
  'https://api.ahrvo.network/payments/na/payment_instruments' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PAYMENT_CARD",
    "identity": "IDentityExample123",
    "number": "4111111111111111",
    "expiration_month": 12,
    "expiration_year": 2025,
    "security_code": "123",
    "name": "John Doe",
    "address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "country": "USA"
    },
    "account_updater_enabled": true
  }'

Example Response (Payment Card)

{
  "id": "PIpaymentCardExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z",
  "type": "PAYMENT_CARD",
  "identity": "IDentityExample123",
  "enabled": true,
  "fingerprint": "FPR-123456789",
  "currency": "USD",
  "name": "John Doe",
  "brand": "VISA",
  "last_four": "1111",
  "expiration_month": 12,
  "expiration_year": 2025,
  "account_updater_enabled": true,
  "network_token_enabled": false,
  "security_code_verification": "MATCHED",
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "address": {
    "line1": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "tags": {},
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
    }
  }
}

Example Request (Bank Account)

curl -X POST \
  'https://api.ahrvo.network/payments/na/payment_instruments' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BANK_ACCOUNT",
    "identity": "IDentityExample123",
    "account_number": "123456789",
    "bank_code": "021000021",
    "account_type": "CHECKING",
    "name": "John Doe",
    "country": "USA",
    "currency": "USD"
  }'

Example Response (Bank Account)

{
  "id": "PIbankAccountExample456",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z",
  "type": "BANK_ACCOUNT",
  "identity": "IDentityExample123",
  "enabled": true,
  "fingerprint": "FPR-987654321",
  "currency": "USD",
  "name": "John Doe",
  "account_type": "CHECKING",
  "bank_code": "021000021",
  "masked_account_number": "XXXXX6789",
  "bank_account_validation_check": "VALID",
  "tags": {},
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIbankAccountExample456"
    }
  }
}

Additional Information

• PCI Compliance: Never submit raw card data directly to this endpoint in production. Use Ahrvo Network hosted fields or tokenization services
• Card Brands Supported: VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, JCB, DINERS_CLUB, CHINA_UNION_PAY
• Account Updater: When enabled, card details are automatically updated when issuers provide new card numbers or expiration dates
• Network Tokenization: Enhances security by replacing card details with network tokens
• Bank Account Validation: USA bank accounts are validated using routing number validation and optionally micro-deposit verification
• Canadian Bank Accounts: Require both institution_number and transit_number in addition to account number
• Fingerprinting: Each unique card/bank account receives a unique fingerprint for duplicate detection
• Security: Card numbers and CVV codes are never stored in plain text; account numbers are masked in API responses
• Verification Results:
  • security_code_verification: MATCHED, UNMATCHED, or UNKNOWN
  • address_verification: MATCHED, NO_MATCH, PARTIAL_MATCH, POSTAL_CODE_AND_STREET_MATCH, or UNKNOWN