Create an Identity

Suggest Edits

---

Overview

Create an Identity for a Buyer, Recipient, or Seller. The Identity resource represents a person or business and is the primary way to onboard participants in the payment system. Identities can represent merchants, customers, or payment recipients.

---

Resource Access

Production (api.ahrvo.network)

POST https://api.ahrvo.network/payments/na/identities

Staging (gateway.ahrvo.network)

POST http://gateway.ahrvo.network/payments/na/identities

---

Arguments

Attribute	Mandatory / Optional	Description
type	Mandatory	The entity type (BUSINESS or PERSONAL)
identity_roles	Mandatory	Array of roles (SELLER, RECIPIENT, BUYER)
entity	Mandatory	Object containing person or business details
additional_underwriting_data	Optional	Additional business and compliance information
tags	Optional	Key-value metadata

Entity Fields (Personal)

Attribute	Mandatory / Optional	Description
first_name	Mandatory	First name
last_name	Mandatory	Last name
email	Mandatory	Email address
phone	Mandatory	Phone number
personal_address	Mandatory	Residential address object
dob	Mandatory	Date of birth (year, month, day)
tax_id	Mandatory	SSN or Tax ID

Entity Fields (Business)

Attribute	Mandatory / Optional	Description
business_name	Mandatory	Legal business name
business_type	Mandatory	Entity type (INDIVIDUAL_SOLE_PROPRIETORSHIP, CORPORATION, LLC, etc.)
business_address	Mandatory	Business address object
business_phone	Mandatory	Business phone number
business_tax_id	Mandatory	EIN or business tax ID
doing_business_as	Optional	DBA name
first_name	Mandatory	Principal owner first name
last_name	Mandatory	Principal owner last name
email	Mandatory	Contact email
dob	Mandatory	Principal owner date of birth
mcc	Optional	Merchant Category Code
annual_card_volume	Optional	Expected annual card volume (in cents)
max_transaction_amount	Optional	Maximum single transaction amount (in cents)

---

Example Request (Business Identity)

curl -X POST https://gateway.ahrvo.network/payments/na/identities \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -d '{
    "type": "BUSINESS",
    "identity_roles": ["SELLER"],
    "entity": {
      "business_name": "Acme Corporation",
      "business_type": "CORPORATION",
      "doing_business_as": "Acme Store",
      "business_address": {
        "line1": "123 Business St",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "USA"
      },
      "business_phone": "4155551234",
      "business_tax_id": "123456789",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "phone": "4155551234",
      "dob": {
        "year": 1985,
        "month": 6,
        "day": 15
      },
      "personal_address": {
        "line1": "456 Personal Ave",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94102",
        "country": "USA"
      },
      "tax_id": "987654321",
      "mcc": "5812",
      "annual_card_volume": 1200000000,
      "max_transaction_amount": 500000
    },
    "tags": {
      "merchant_tier": "premium",
      "onboarding_date": "2025-12-10"
    }
  }'

---

Example Response

{
  "id": "IDxxxxxxxxxxxxxxxxxx",
  "created_at": "2025-12-10T18:00:00Z",
  "updated_at": "2025-12-10T18:00:00Z",
  "application": "APxxxxxxxxxxxxxxxxxx",
  "type": "BUSINESS",
  "identity_roles": ["SELLER"],
  "entity": {
    "business_name": "Acme Corporation",
    "business_type": "CORPORATION",
    "doing_business_as": "Acme Store",
    "business_address": {
      "line1": "123 Business St",
      "line2": null,
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "country": "USA"
    },
    "business_phone": "4155551234",
    "business_tax_id_provided": true,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@acme.com",
    "phone": "4155551234",
    "dob": {
      "year": 1985,
      "month": 6,
      "day": 15
    },
    "personal_address": {
      "line1": "456 Personal Ave",
      "line2": null,
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94102",
      "country": "USA"
    },
    "tax_id_provided": true,
    "mcc": "5812",
    "annual_card_volume": 1200000000,
    "max_transaction_amount": 500000
  },
  "tags": {
    "merchant_tier": "premium",
    "onboarding_date": "2025-12-10"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APxxxxxxxxxxxxxxxxxx"
    },
    "merchants": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDxxxxxxxxxxxxxxxxxx/merchants"
    }
  }
}

---

Identity Types

• BUSINESS: For business entities (requires business and principal owner information)
• PERSONAL: For individual persons (requires personal information only)

Identity Roles

• SELLER: Merchant who accepts payments
• RECIPIENT: Receives payouts or disbursements
• BUYER: Customer making payments

---

API Documentation

---