Create an Onboarding Form

Overview

Create an onboarding_form resource to generate a unique link for a user to complete the onboarding process. This endpoint uses Ahrvo Network-hosted pre-built forms to collect Identity and verification data from users. Only ROLE_PARTNER credentials can be used.

Resource Access

• User Permissions: Partner role only (ROLE_PARTNER)
• Endpoint: POST /onboarding_forms

Arguments

Parameter	Type	Required	Description
merchant_processors	array	Yes	List of processors the user can be onboarded to
merchant_processors[].processor	string	Yes	The processor to onboard (e.g., DUMMY_V1)
onboarding_link_details	object	Yes	Configuration for the onboarding link
onboarding_link_details.return_url	string	Yes	URL the user is redirected to after successful completion
onboarding_link_details.expired_session_url	string	Yes	URL the user is redirected to if the link expires
onboarding_link_details.terms_of_service_url	string	Yes	URL linking to the platform's terms of service
onboarding_link_details.fee_details_url	string	No	URL linking to the platform's fee details
onboarding_link_details.expiration_in_minutes	integer	No	Time until the link expires (default: 10080 minutes / 7 days)
onboarding_data	object	No	Pre-populate data fields on the form

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/onboarding_forms' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_processors": [
      {
        "processor": "DUMMY_V1"
      }
    ],
    "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",
      "fee_details_url": "https://yourplatform.com/fees",
      "expiration_in_minutes": 1440
    },
    "onboarding_data": {
      "entity": {
        "business_name": "Acme Retail",
        "email": "john@acmeretail.com",
        "phone": "555-123-4567"
      }
    }
  }'

Example Response

{
  "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",
      "phone": "555-123-4567"
    },
    "associated_entities": [],
    "payment_instruments": null,
    "additional_underwriting_data": {},
    "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",
    "fee_details_url": "https://yourplatform.com/fees",
    "expiration_in_minutes": 1440
  },
  "onboarding_link": {
    "expires_at": "2023-06-16T10:30:00Z",
    "link_url": "https://forms.finix.com/onboarding/OFonboardingFormExample123?token=abc123xyz"
  },
  "tags": {}
}

Additional Information

• Form Status:
  • IN_PROGRESS: Form has been created but not completed by the user
  • COMPLETED: User has successfully completed the form
  • EXPIRED: The onboarding link has expired
• Link Expiration: The default expiration time is 10080 minutes (7 days). You can customize this using the expiration_in_minutes parameter
• Pre-population: You can pre-fill form fields by including data in the onboarding_data object, reducing the amount of information users need to enter
• Identity Creation: Once the user completes the form (status = COMPLETED), an Identity is automatically created and its ID is populated in the identity_id field
• Merchant Processors: You can specify multiple processors in the array, allowing the user to choose which processor to onboard to
• Form Fields Collected:
  • Entity Information: Business name, contact details, addresses, tax IDs
  • Associated Entities: Beneficial owners and principals (for businesses)
  • Payment Instruments: Bank account information for settlements
  • Underwriting Data: Business description, refund policy, transaction volumes, MCC
• Security: The generated link is single-use and time-limited. After expiration, you can create a new link using the Create Onboarding Form Link endpoint
• Partner Credentials Required: This endpoint can only be accessed with ROLE_PARTNER credentials, not standard user credentials