Skip to navigation
Manage payment operationsMerchant boardingAPI

Manage paypoints with the API

Beta
Learn how to create, read, update, and list boarding paypoints with the Payabli API
View as MarkdownOpen in Claude
Applies to:Developers

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

A paypoint is the entity that moves money for a business. A paypoint set up for Pay In is a merchant, but it can also be set up for Pay Out, or both. A business can have many paypoints, each with its own status and settings. Use the paypoints API to create and manage them as part of boarding. For how paypoints fit into the wider model, see the boarding overview.

Considerations

  • The boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
  • A paypoint boards under a business. Provide either a businessReference for an existing business, or a business object to create one inline.

Create a paypoint

Send a POST request to /v2/paypoints with the paypoint’s doingBusinessAs and the business it boards under. Provide either a businessReference for an existing business, or a business object to create one inline. New paypoints start in pending. See the API reference for this endpoint for full documentation.

POST
/api/v2/paypoints
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",
  "customerServiceEmail": "support@example.com",
  "customerServicePhone": "3055551212",
  "description": "Boutique flower shop",
  "doingBusinessAs": "Rose Gardens",
  "paypointType": "merchant",
  "timezone": "America/New_York",
  "website": "https://example.com"
}'
Try it

The response returns the new paypoint’s reference and initial status:

Response
{
  "success": true,
  "message": "Paypoint created successfully",
  "traceId": "0HNNN6HH5NDB3:00000001",
  "data": {
    "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
    "paypointStatus": "pending",
    "createdAt": "2026-08-11T10:36:04.1157718Z",
    "_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"
  }
}

To create the business inline instead, send a business object rather than a businessReference:

POST
/api/v2/paypoints
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"
}'
Try it

The paypointReference in the response is the reference you use to read and manage the paypoint.

Get a paypoint

Send a GET request to /v2/paypoints/{paypointReference}. See the API reference for this endpoint for full documentation.

GET
/api/v2/paypoints/:paypointReference
curl https://api-sandbox.payabli.com/api/v2/paypoints/019ff064-c690-7679-a73e-688418aadc7c \
     -H "Authorization: Bearer <token>"
Try it

The response returns the paypoint’s full detail:

Response
{
  "success": true,
  "message": "Paypoint retrieved successfully",
  "traceId": "0HNNN6HH5NDB3:00000002",
  "data": {
    "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",
    "description": "Boutique flower shop",
    "website": "https://example.com",
    "timezone": "America/New_York",
    "customerServicePhone": "3055551212",
    "customerServiceEmail": "support@example.com"
  }
}

List paypoints

Send a GET request to /v2/paypoints. Filter and page the results with the query parameters: businessReference, status, search, limit, and page. 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 limit=1 \
     -d page=1
Try it

The response returns a page of paypoints with pagination metadata:

Response
{
  "success": true,
  "message": "Paypoints retrieved successfully",
  "traceId": "0HNNN6HH5NDBG:00000018",
  "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",
        "description": "Boutique flower shop",
        "website": "https://example.com",
        "timezone": "America/New_York",
        "customerServicePhone": "3055551212",
        "customerServiceEmail": "support@example.com"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 1
  }
}

Update a paypoint

Send a PATCH request to /v2/paypoints/{paypointReference} with only the fields you want to change. See the API reference for this endpoint for full documentation.

PATCH
/api/v2/paypoints/:paypointReference
curl -X PATCH https://api-sandbox.payabli.com/api/v2/paypoints/019ff064-c690-7679-a73e-688418aadc7c \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "description": "Updated description"
}'
Try it

The response confirms the update and returns the new timestamp:

Response
{
  "success": true,
  "message": "Paypoint updated successfully",
  "traceId": "0HNNN6HH5ND71:00000268",
  "data": {
    "paypointReference": "019ff064-c690-7679-a73e-688418aadc7c",
    "updatedAt": "2026-08-11T10:36:04.462751Z",
    "_links": {
      "self": "/v2/paypoints/019ff064-c690-7679-a73e-688418aadc7c"
    }
  }
}

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