Skip to main content

Fetch an Onboarding Form

Overview​

Retrieve the details of an onboarding_form, including collected data (if completed) and the generated link. This endpoint allows you to check the status of the onboarding process and access the data submitted by users.

Resource Access​

  • User Permissions: Partner role only (ROLE_PARTNER)
  • Endpoint: GET /onboarding_forms/\{onboarding_form_id}

Arguments​

ParameterTypeRequiredDescription
onboarding_form_idstringYesThe unique ID of the onboarding_form

Example Request​

curl -X GET \
  'https://api.ahrvo.network/payments/na/onboarding_forms/OFonboardingFormExample123' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response (IN_PROGRESS)​

{
  "id": "OFonboardingFormExample123",
  "status": "IN_PROGRESS",
  "identity_id": null,
  "application_id": "APapplicationExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z",
  "merchant_processors": [
    {
      "processor": "DUMMY_V1"
    }
  ],
  "onboarding_data": {
    "entity": {
      "business_name": "Acme Retail",
      "email": "john@acmeretail.com"
    },
    "associated_entities": [],
    "payment_instruments": null,
    "additional_underwriting_data": {}
  },
  "onboarding_link_details": {
    "return_url": "https://yourplatform.com/onboarding/success",
    "expired_session_url": "https://yourplatform.com/onboarding/expired",
    "terms_of_service_url": "https://yourplatform.com/terms",
    "expiration_in_minutes": 1440
  },
  "onboarding_link": {
    "expires_at": "2023-06-16T10:30:00Z",
    "link_url": "https://forms.finix.com/onboarding/OFonboardingFormExample123?token=abc123xyz"
  },
  "tags": {}
}

Example Response (COMPLETED)​

{
  "id": "OFonboardingFormExample123",
  "status": "COMPLETED",
  "identity_id": "IDcreatedIdentity456",
  "application_id": "APapplicationExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T11:45:00Z",
  "merchant_processors": [
    {
      "processor": "DUMMY_V1"
    }
  ],
  "onboarding_data": {
    "entity": {
      "business_name": "Acme Retail Store",
      "email": "john@acmeretail.com",
      "phone": "555-123-4567",
      "first_name": "John",
      "last_name": "Doe",
      "title": "Owner",
      "business_type": "LIMITED_LIABILITY_COMPANY",
      "doing_business_as": "Acme Store",
      "business_address": {
        "line1": "123 Main Street",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "USA"
      },
      "business_tax_id": "12-XXX3456",
      "mcc": "5411",
      "url": "https://www.acmeretail.com",
      "default_statement_descriptor": "ACME RETAIL",
      "annual_card_volume": 1000000
    },
    "associated_entities": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "title": "CFO",
        "email": "jane@acmeretail.com",
        "phone": "555-987-6543",
        "dob": {
          "year": 1985,
          "month": 3,
          "day": 15
        },
        "personal_address": {
          "line1": "456 Oak Avenue",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94102",
          "country": "USA"
        },
        "tax_id": "XXX-XX-1234",
        "principal_percentage_ownership": 30
      }
    ],
    "payment_instruments": {
      "name": "Acme Retail Settlement Account",
      "bank_code": "123456789",
      "account_number": "XXXXX1234",
      "account_type": "BUSINESS_CHECKING",
      "type": "BANK_ACCOUNT"
    },
    "additional_underwriting_data": {
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "business_description": "Retail grocery store selling fresh produce and packaged goods",
      "card_volume_distribution": {
        "ecommerce_percentage": 20,
        "card_present_percentage": 70,
        "mail_order_telephone_order_percentage": 10
      },
      "max_transaction_amount": 50000,
      "merchant_agreement_accepted": true,
      "merchant_agreement_timestamp": "2023-06-15T11:30:00Z",
      "merchant_agreement_ip_address": "192.168.1.100"
    },
    "country": "USA"
  },
  "onboarding_link_details": {
    "return_url": "https://yourplatform.com/onboarding/success",
    "expired_session_url": "https://yourplatform.com/onboarding/expired",
    "terms_of_service_url": "https://yourplatform.com/terms"
  },
  "onboarding_link": {
    "expires_at": "2023-06-16T10:30:00Z",
    "link_url": "https://forms.finix.com/onboarding/OFonboardingFormExample123?token=abc123xyz"
  },
  "tags": {}
}

Additional Information​

  • Form Statuses:
    • IN_PROGRESS: User has not yet completed the form
    • COMPLETED: User successfully submitted all required information
    • EXPIRED: The onboarding link has expired without completion
  • Identity Creation: When status is COMPLETED, an Identity is automatically created and the identity_id field is populated
  • Data Collection: The onboarding_data object contains all information collected from the user:
    • entity: Primary business/individual information
    • associated_entities: Beneficial owners and principals (required for businesses with ownership >25%)
    • payment_instruments: Bank account for settlements
    • additional_underwriting_data: Business operations, refund policies, transaction volumes, merchant agreement acceptance
  • Sensitive Data Masking: Tax IDs and account numbers are masked in the response (e.g., XXX-XX-1234)
  • Next Steps After Completion:
    1. Use the identity_id to create a Merchant
    2. Create a Verification to complete underwriting
    3. Upon approval, the merchant can begin processing payments
  • Webhook Events: You can configure webhooks to be notified when the form status changes to COMPLETED
  • Link Expiration: If the form is expired, you can create a new link using the Create Onboarding Form Link endpoint