Skip to navigation
Manage payment operationsMerchant boardingAPIWorkflows

Request more services with the API

Beta
Learn how to request more Pay In or Pay Out services for a paypoint that's already boarded
View as MarkdownOpen in Claude
Applies to:Developers

Intelligent boarding is in beta. To opt in, reach out to your Payabli contact.

A paypoint that’s already boarded can request more services, such as Pay Out for a paypoint that boarded for Pay In. To request new services, create a new application for the paypoint and list the services to add in the services object of the request body. You don’t create a new business or paypoint, and the new application goes through review. For how applications work, see Manage applications with the API.

Considerations

  • The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
  • You need the businessReference of the business that owns the paypoint.
  • Request only services the paypoint doesn’t already have. Payabli doesn’t board a service again for a paypoint that already has it. List Pay In services under moneyIn and Pay Out services under moneyOut.

Find the paypoint

Send a GET request to /v2/paypoints with the businessReference query parameter to list the business’s paypoints. See the API reference for this endpoint for full documentation.

GET
/api/v2/paypoints
curl -G https://api-sandbox.payabli.com/api/v2/paypoints \
     -H "Authorization: Bearer <token>" \
     -d businessReference=019fed1a-3d6e-75d3-a81e-cba3874b0a55
Try it

The response lists the business’s paypoints. Note the paypointReference of the paypoint that needs the new services:

Response
{
  "success": true,
  "message": "Paypoints retrieved successfully",
  "traceId": "0HNONVR8FHLEO:0000005A",
  "data": {
    "items": [
      {
        "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
        "parentPaypointReference": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
        "paypointStatus": "pending",
        "entryName": "8cfec329267",
        "createdAt": "2026-08-11T10:36:04.115771",
        "updatedAt": "2026-08-11T10:36:04.115788",
        "_links": {
          "self": "/v2/paypoints/019ff064-c690-7679-a73e-688418aadc7c",
          "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
        },
        "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
        "paypointType": "merchant",
        "doingBusinessAs": "Rose Gardens"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 25
  }
}

Create an application for the paypoint

Send a POST request to /v2/requests with the businessReference, the paypointReference, and a services object that lists the services to add. Include requestTemplate with the reference of your organization’s boarding template, because Payabli reviews the application with the template’s underwriting settings. The paypoint must belong to the business. If it doesn’t, the request fails with 404. See the API reference for this endpoint for full documentation.

POST
/api/v2/requests
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": "019ff064-c690-7679-a73e-688418aadc7c",
  "externalId": "APP-2025-0418",
  "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
  "tags": [
    "add-services"
  ],
  "services": {
    "moneyOut": [
      "Ach",
      "Check"
    ]
  }
}'
Try it

The response returns the new application in draft, with the requested services:

Response
{
  "success": true,
  "message": "Application created successfully",
  "traceId": "0HNONVRI1TBG9:00000029",
  "data": {
    "requestsReference": "4463979d-6336-4298-90cb-52d446030874",
    "businessReference": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "applicationStatus": "draft",
    "applicationStatusCode": 1,
    "allowedActions": [
      "submit",
      "withdraw",
      "abandon"
    ],
    "createdAt": "2026-09-28T15:48:54.0628351Z",
    "_links": {
      "self": "/v2/requests/4463979d-6336-4298-90cb-52d446030874",
      "business": "/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
    "paypointStatus": "active",
    "externalId": "APP-2025-0418",
    "parent": "a8806f02-23b3-4f6d-bba3-42e1b94326ea",
    "parentOrgName": "PropertyManager Pro",
    "requestTemplate": "019ff129-d393-7761-9a31-e5afe85b4081",
    "services": {
      "moneyOut": [
        "Ach",
        "Check"
      ]
    },
    "tags": [
      "add-services"
    ]
  }
}

The requestsReference in the response identifies the new application.

Choose the signer

Every application needs exactly one signer, and both validate and submit check for one. The signer must be an owner, flagged with isSigner on their link to the business. If the business doesn’t have a signer yet, or the signer has changed, send a PATCH request to /v2/businesses/{businessReference}/people/{personReference} with isSigner set to true. Setting a new signer removes the flag from the person who had it. You can also choose the signer at submit with signer.personReference, but validate doesn’t see that choice, so setting the flag first lets you validate the full application. See Manage the people on a business.

Payabli takes the signer’s identity from their person record and business link when you submit, so check that their details are current.

Validate the application

New services can require details that the paypoint’s first boarding didn’t, because different services have different requirements. Before you submit, check that the business, its people, and its payment methods have everything the new services need. Send a POST request to /v2/requests/{requestsReference}/validate. See the API reference for this endpoint for full documentation.

POST
/api/v2/requests/:requestsReference/validate
curl -X POST https://api-sandbox.payabli.com/api/v2/requests/4463979d-6336-4298-90cb-52d446030874/validate \
     -H "Authorization: Bearer <token>"
Try it

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

Response
{
  "success": true,
  "message": "Validation completed",
  "traceId": "0HNONVRI1TD2T:00000012",
  "data": {
    "valid": true,
    "servicesEvaluated": [
      "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. servicesEvaluated names the requested services with Payabli’s internal service names, such as payInCard for the Card Pay In service.

Response
{
  "success": true,
  "message": "Validation completed",
  "traceId": "0HNONVR8FHN0R:00000017",
  "data": {
    "valid": false,
    "servicesEvaluated": [
      "payInCard",
      "payInAch"
    ],
    "sections": {
      "business": {
        "complete": false,
        "missingFields": [
          {
            "field": "business.description",
            "label": "Business Description",
            "reason": "required"
          },
          {
            "field": "business.legalStructure",
            "label": "Legal Structure",
            "reason": "required"
          },
          {
            "field": "business.establishedDate",
            "label": "Established Date",
            "reason": "required"
          },
          {
            "field": "business.incorporationState",
            "label": "Formation State",
            "reason": "required"
          },
          {
            "field": "business.merchantCatCode",
            "label": "Industry (MCC)",
            "reason": "required"
          },
          {
            "field": "business.taxReference",
            "label": "Tax ID (EIN/SSN)",
            "reason": "required"
          },
          {
            "field": "business.taxIdCountry",
            "label": "Tax ID Country",
            "reason": "required"
          },
          {
            "field": "business.isForeignOwned",
            "label": "Foreign Owned",
            "reason": "required"
          },
          {
            "field": "business.operatingSeasons",
            "label": "Operating Seasons",
            "reason": "required"
          },
          {
            "field": "business.phone",
            "label": "Business Phone",
            "reason": "required"
          },
          {
            "field": "business.emails",
            "label": "Business Email",
            "reason": "required"
          },
          {
            "field": "business.addressDetails",
            "label": "Business Address",
            "reason": "required"
          }
        ]
      },
      "salesAndPayments": {
        "complete": false,
        "missingFields": [
          {
            "field": "business.processingMetrics.monthlyReceivablesVolume",
            "label": "Annual Payment Volume",
            "reason": "required"
          },
          {
            "field": "business.processingMetrics.largestReceivableSize",
            "label": "Largest Transaction",
            "reason": "required"
          },
          {
            "field": "business.processingMetrics.environments",
            "label": "Payment Environment",
            "reason": "required"
          },
          {
            "field": "business.processingMetrics.numberOfTransactions",
            "label": "Monthly Payment Count",
            "reason": "required"
          }
        ]
      },
      "banking": {
        "complete": false,
        "missingFields": [
          {
            "field": "paymentMethods",
            "label": "At least one payment method is required",
            "reason": "required"
          }
        ]
      },
      "people": {
        "complete": false,
        "missingFields": [
          {
            "field": "people",
            "label": "At least one owner or officer is required",
            "reason": "required"
          }
        ]
      }
    }
  }
}

Submit the application

Send a POST request to /v2/requests/{requestsReference}/submit with the new application’s requestsReference, and include a signer with the signature details. See Submit an application for the request and response.

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.

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