Add a location for a business with the API

When a business that’s already on Payabli opens a new location, board the location as a new paypoint for the same business. The new paypoint uses the business’s existing details, people, and bank accounts, so you don’t enter them again. You create the paypoint, then open an application for it that lists the services the location needs, validate it, and submit it for review. For how businesses and paypoints fit together, see Boarding overview.

Considerations

• The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
• You need the businessReference of the business that’s opening the location.
• A business can have more than one application open at a time, one for each paypoint. Send the new paypoint’s paypointReference when you create the application. If you leave it out, Payabli picks one of the business’s paypoints for you.

Create the location’s paypoint

Send a POST request to /v2/paypoints with the businessReference and the location’s doingBusinessAs. Payabli creates the paypoint under the existing business, and the paypoint starts in pending. 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 '{
  "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
  "doingBusinessAs": "Rose Gardens Downtown",
  "paypointType": "merchant",
  "timezone": "America/New_York"
}'

The response returns the new paypoint. Note its paypointReference for the next step:

{
  "success": true,
  "message": "Paypoint created successfully",
  "traceId": "0HNP8M3LB1GJU:0000008B",
  "data": {
    "paypointReference": "019ff3a8-2c41-7b0e-9d52-6e1f0c84a7b3",
    "paypointStatus": "pending",
    "createdAt": "2026-10-13T14:38:25.9924683Z",
    "_links": {
      "self": "/v2/paypoints/019ff3a8-2c41-7b0e-9d52-6e1f0c84a7b3",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "doingBusinessAs": "Rose Gardens Downtown",
    "timezone": "America/New_York"
  }
}

Create the application

Send a POST request to /v2/requests with the businessReference, the new paypoint’s paypointReference, and a services object that lists the services the location 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. 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",
  "paypointReference": "019ff3a8-2c41-7b0e-9d52-6e1f0c84a7b3",
  "externalId": "APP-2026-1013",
  "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
  "services": {
    "moneyIn": [
      "Card"
    ]
  }
}'

The response returns the new application in draft, linked to the new paypoint. The requestsReference identifies the application in the next steps:

{
  "success": true,
  "message": "Application created successfully",
  "traceId": "0HNP8M4GTH3JG:00000003",
  "data": {
    "requestsReference": "b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406",
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "applicationStatus": "draft",
    "applicationStatusCode": 1,
    "allowedActions": [
      "submit",
      "withdraw",
      "abandon"
    ],
    "createdAt": "2026-10-13T14:42:31.0326419Z",
    "_links": {
      "self": "/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "paypointReference": "019ff3a8-2c41-7b0e-9d52-6e1f0c84a7b3",
    "paypointStatus": "pending",
    "externalId": "APP-2026-1013",
    "parent": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "parentOrgName": "PropertyManager Pro",
    "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
    "services": {
      "moneyIn": [
        "Card"
      ]
    }
  }
}

Validate the application

Check that the business, its people, and its payment methods have everything the requested services need. 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/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/validate \
     -H "Authorization: Bearer <token>"

When the location requests the same services as the business’s other paypoints, the business already has everything validation checks, so the application can be valid right away:

{
  "success": true,
  "message": "Validation completed",
  "traceId": "0HNP8M4GTH3J0:00000015",
  "data": {
    "valid": true,
    "servicesEvaluated": [
      "payInCard"
    ],
    "sections": {
      "business": {
        "complete": true,
        "missingFields": []
      },
      "salesAndPayments": {
        "complete": true,
        "missingFields": []
      },
      "banking": {
        "complete": true,
        "missingFields": []
      },
      "people": {
        "complete": true,
        "missingFields": []
      }
    }
  }
}

When the location requests services the business’s other paypoints don’t have, those services can require fields that aren’t on file yet. In that case, valid is false and each section lists its missingFields. The field value is the path on the record to fix, such as business.taxReference. Update that record, then validate again. A new location’s application can also require documents, even for services the business already has, because document requirements belong to each application. 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.

Submit the application

Send a POST request to /v2/requests/{requestsReference}/submit with a signer object that holds the signature details. The signer must be an owner of the business. For how to choose the signer, see Submit an application. See the API reference for this endpoint for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/requests/b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406/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": "0HNP8M4GTH3IP:0000001B",
  "data": {
    "requestsReference": "b7e2c915-4f0a-4d6b-a3c8-91e5d2f7c406",
    "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.