Board a new business with the API

To board a business that’s new to Payabli, create its paypoint first, with the business created in the same request. Then add the business’s owner, open an application that lists the services the business needs, validate it, and submit it for review. This quickstart walks through each step. For how the business, its people, its paypoint, and its applications fit together, see Boarding overview.

Considerations

• The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
• Each service has its own requirements. Validate reports fields that are missing or invalid, so you can fix them before you submit. For the fields boarding asks for, see Required fields for boarding applications.
• Every application needs a signer, and the signer must be an owner. The business also needs a primary controller. Unless its legal structure is government or non-profit, it also needs at least one owner with 25% ownership or more.

Create the paypoint and business

Send a POST request to /v2/paypoints with the paypoint’s details and a business object that describes the business. Payabli creates both, and the paypoint starts in pending. Only doingBusinessAs and business.legalName are required to create the paypoint. Validate tells you what else the requested services need. To set up the business’s bank accounts in the same request, add them to business.paymentMethods, as described in Manage payment methods with the API. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/paypoints \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "business": {
    "emails": [
      "ops@example.com"
    ],
    "externalId": "rg-001",
    "legalName": "Rose Gardens LLC",
    "legalStructure": "llc",
    "merchantCatCode": "5814",
    "parentReference": "8cfec329267",
    "phone": [
      "3055551212"
    ],
    "taxReference": "477498993",
    "website": "https://example.com"
  },
  "customerServiceEmail": "support@example.com",
  "customerServicePhone": "3055551212",
  "description": "Boutique flower shop",
  "doingBusinessAs": "Rose Gardens",
  "paypointType": "merchant",
  "timezone": "America/New_York",
  "website": "https://example.com"
}'

The response returns the new paypoint. Note the businessReference and paypointReference for the next steps:

{
  "success": true,
  "message": "Paypoint created successfully",
  "traceId": "0HNNN6HH5NDOA:00000001",
  "data": {
    "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
    "paypointStatus": "pending",
    "createdAt": "2026-08-11T13:09:48.9047501Z",
    "_links": {
      "self": "/v2/paypoints/019ff064-c690-7679-a73e-688418aadc7c",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "doingBusinessAs": "Rose Gardens",
    "timezone": "America/New_York"
  }
}

Add the owner

Send a POST request to /v2/people with the owner’s details and a businessRelationship object that links them to the business. In businessRelationship, set personType to Owner with their ownershipPercentage, set isPrimaryController to true, and set isSigner to true to make them the person who signs the application. To add more owners or other people, send one request for each person. See Manage people with the API. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/people \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "firstName": "Marcus",
  "lastName": "Delgado",
  "middleName": "James",
  "primaryEmail": "marcus.delgado@example.com",
  "secondaryEmail": "m.delgado@example.net",
  "primaryPhoneNumber": "3055551212",
  "secondaryPhoneNumber": "3055559876",
  "dateOfBirth": "1985-03-14",
  "ssn": "412-55-9021",
  "nationality": "US",
  "driversLicenseNumber": "D1234567",
  "driversLicenseState": "FL",
  "externalId": "person-001",
  "customData": {
    "department": "finance"
  },
  "addresses": [
    {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 400",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "legal"
    }
  ],
  "identificationDocuments": [
    {
      "type": "passport",
      "number": "X1234567",
      "issuingCountry": "US",
      "expirationDate": "2030-06-30"
    }
  ],
  "businessRelationship": {
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "personType": "Owner",
    "ownershipPercentage": 100,
    "isPrimaryController": true,
    "isSigner": true,
    "title": "CEO",
    "primaryEmail": "contact@example.com",
    "secondaryEmail": "contact.alt@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33101",
      "country": "US",
      "type": "billing"
    },
    "mailingAddress": {
      "addressLine1": "456 Oak Avenue",
      "cityLocality": "Miami",
      "stateProvince": "FL",
      "postalCode": "33102",
      "country": "US",
      "type": "mailing"
    }
  }
}'

The response returns the new person, with their link to the business:

{
  "success": true,
  "message": "Person created successfully",
  "traceId": "0HNNQ4R2OT26Q:0000001D",
  "data": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "firstName": "Marcus",
    "lastName": "Delgado",
    "verificationStatus": "not_started",
    "createdAt": "2026-08-14T17:24:31.3877241Z",
    "lastUpdated": "2026-08-14T17:24:31.3877242Z",
    "_links": {
      "self": "/v2/people/01a0014d-ce1a-7110-9bac-c4c59647a88d",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "externalId": "person-001",
    "middleName": "James",
    "primaryEmail": "marcus.delgado@example.com",
    "secondaryEmail": "m.delgado@example.net",
    "primaryPhoneNumber": "3055551212",
    "secondaryPhoneNumber": "3055559876",
    "dateOfBirth": "****-**-14",
    "ssn": "***-**-9021",
    "nationality": "US",
    "driversLicenseNumber": "D1***567",
    "driversLicenseState": "FL",
    "customData": {
      "department": "finance"
    },
    "businessRelationship": {
      "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
      "personType": "owner",
      "ownershipPercentage": 100,
      "beneficialOwner": true,
      "isPrimaryController": true,
      "isSigner": true,
      "title": "CEO",
      "primaryEmail": "contact@example.com",
      "secondaryEmail": "contact.alt@example.net",
      "primaryPhoneNumber": "3055551212",
      "secondaryPhoneNumber": "3055559876",
      "billingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a891",
      "mailingAddressUuid": "01a0014d-ce1a-7110-9bac-c4c59647a892"
    }
  }
}

Create the application

Send a POST request to /v2/requests with the businessReference and a services object that lists the services the business needs. List Pay In services under moneyIn and Pay Out services under moneyOut. Include requestTemplate with the reference of your organization’s boarding template, because Payabli reviews the application with the template’s underwriting settings. The application boards the paypoint you created in the first step. An application needs a paypoint, so this request fails with 404 if the business doesn’t have one. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/requests \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
  "externalId": "APP-2025-0417",
  "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
  "services": {
    "moneyIn": [
      "Ach",
      "Card"
    ],
    "moneyOut": [
      "Ach",
      "Check"
    ]
  }
}'

The response returns the new application in draft. The requestsReference identifies the application in the next steps:

{
  "success": true,
  "message": "Application created successfully",
  "traceId": "0HNONVRI1TBCP:00000054",
  "data": {
    "requestsReference": "3f3caa7b-bdfe-4bf1-814b-30d54859247c",
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "applicationStatus": "draft",
    "applicationStatusCode": 1,
    "allowedActions": [
      "submit",
      "withdraw",
      "abandon"
    ],
    "createdAt": "2026-07-01T15:00:01.734346Z",
    "_links": {
      "self": "/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
    "paypointStatus": "pending",
    "externalId": "APP-2025-0417",
    "parent": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "parentOrgName": "PropertyManager Pro",
    "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
    "services": {
      "moneyIn": [
        "Ach",
        "Card"
      ],
      "moneyOut": [
        "Ach",
        "Check"
      ]
    }
  }
}

Validate the application

Check that the business, its people, and its payment methods have everything the requested services need, and that their values are valid. Send a POST request to /v2/requests/{requestsReference}/validate. Validation doesn’t change the application. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/validate \
     -H "Authorization: Bearer <token>"

When valid is true, the records have everything the requested services need:

{
  "success": true,
  "message": "Validation completed",
  "traceId": "0HNP4OM1AUIEG:00000008",
  "data": {
    "valid": true,
    "servicesEvaluated": [
      "payInCard",
      "payInAch",
      "payOutAch",
      "payOutCheck"
    ],
    "sections": {
      "business": {
        "complete": true,
        "missingFields": []
      },
      "salesAndPayments": {
        "complete": true,
        "missingFields": []
      },
      "banking": {
        "complete": true,
        "missingFields": []
      },
      "people": {
        "complete": true,
        "missingFields": []
      }
    }
  }
}

When valid is false, each section lists its missingFields. The field value is the path on the record to fix, such as business.taxReference. Update that record, such as with a PATCH request to the business, then validate again. If a field starts with documents., it’s a required document, not a record field: upload the file to the application instead. See Upload documents. For an example response with missing fields, see the API reference for this endpoint.

Submit the application

Send a POST request to /v2/requests/{requestsReference}/submit with a signer object that holds the signature details. Payabli records the signer’s identity from their person record and business link. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/requests/3f3caa7b-bdfe-4bf1-814b-30d54859247c/submit \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "signer": {
    "personReference": "01a0014d-ce1a-7110-9bac-c4c59647a88d",
    "signature": "Marcus J Delgado",
    "signatureType": "type",
    "acceptance": true,
    "pciAttestation": true,
    "reportedSignerIp": "203.0.113.7"
  }
}'

The response returns the application’s new status:

{
  "success": true,
  "message": "Application submitted",
  "traceId": "0HNONVRI1SMEU:0000068E",
  "data": {
    "requestsReference": "3f3caa7b-bdfe-4bf1-814b-30d54859247c",
    "applicationStatus": "submitted",
    "allowedActions": [
      "startVerification",
      "withdraw",
      "abandon",
      "markError"
    ]
  }
}

After you submit the application, it moves through review. To answer underwriting, see Respond to underwriting requests. To follow the application’s progress, see Track status changes.

Related resources

See these related resources to help you get the most out of Payabli.