Skip to navigation
Manage payment operationsMerchant boardingAPI

Manage payment methods with the API

Beta
Learn how to create, read, update, and deactivate payment methods 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 payment method is a bank account attached to a person or business, used to move money. Each payment method has an owner, a type, and a status. Use the payment methods API to add and manage them as you board and operate a paypoint. For how payment methods fit into the wider model, see the boarding overview.

Considerations

  • The API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
  • A payment method belongs to a person or a business. Set accountOwner to that entity’s reference and ownerType to person or business.
  • Reads mask sensitive fields: the account and routing numbers show only the last four digits.

Create payment methods

Send a POST request to /v2/payment-methods with a data array of one or more payment methods. Set each one’s accountOwner and ownerType. See the API reference for this endpoint for full documentation.

POST
/api/v2/payment-methods
curl -X POST https://api-sandbox.payabli.com/api/v2/payment-methods \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "data": [
    {
      "type": "bank_account",
      "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
      "ownerType": "business",
      "accountType": "checking",
      "accountNumber": "123456789",
      "routingNumber": "021000021",
      "usage": [
        "deposits",
        "billing"
      ],
      "nickname": "Operating account",
      "financialInstitution": "Bank of Example"
    }
  ]
}'
Try it

The response returns the created payment methods, each with its reference and token:

Response
{
  "success": true,
  "message": "Payment method created successfully",
  "traceId": "0HNNN6HH5NE18:00000010",
  "data": [
    {
      "paymentMethodReference": "019ff142-454b-7721-96a3-c8628b9d568f",
      "type": "bank_account",
      "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
      "ownerType": "business",
      "status": "PENDING",
      "createdAt": "2026-08-11T14:38:00.0117762Z",
      "lastUpdated": "2026-08-11T14:38:00.0117763Z",
      "_links": {
        "self": "/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f",
        "owner": "/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
      },
      "fingerprint": "2a0c2a64d03492ba45af4d01f329f22b41513411cab7658072739d17ed570675",
      "tokenReference": "deacc32d-81eb-470b-9cff-0ad2fab87096",
      "nickname": "Operating account",
      "financialInstitution": "Bank of Example",
      "accountType": "Checking",
      "accountNumber": "****6789",
      "routingNumber": "*****0021",
      "usage": [
        "deposits",
        "billing"
      ]
    }
  ]
}

The paymentMethodReference in each result is the reference you use to read and manage that payment method.

You can also attach payment methods to a business when you create it, by including them in the business’s paymentMethods. See Manage business entities.

Get a payment method

Send a GET request to /v2/payment-methods/{paymentMethodReference}. Sensitive fields are masked. See the API reference for this endpoint for full documentation.

GET
/api/v2/payment-methods/:paymentMethodReference
curl https://api-sandbox.payabli.com/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f \
     -H "Authorization: Bearer <token>"
Try it

The response returns the payment method’s detail:

Response
{
  "success": true,
  "message": "Payment method retrieved successfully",
  "traceId": "0HNNN6HH5NE0R:00000015",
  "data": {
    "paymentMethodReference": "019ff142-454b-7721-96a3-c8628b9d568f",
    "type": "bank_account",
    "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "ownerType": "business",
    "status": "PENDING",
    "createdAt": "2026-08-11T14:38:00.011776",
    "lastUpdated": "2026-08-11T14:38:00.011776",
    "_links": {
      "self": "/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f",
      "owner": "/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "nickname": "Operating account",
    "financialInstitution": "Bank of Example",
    "accountType": "Checking",
    "accountNumber": "****6789",
    "routingNumber": "*****0021",
    "usage": [
      "deposits",
      "billing"
    ]
  }
}

List payment methods

Send a GET request to /v2/payment-methods. Filter and page the results with the query parameters: accountOwner, ownerType, status, type, limit, page, sortBy, and sortOrder. See the API reference for this endpoint for full documentation.

GET
/api/v2/payment-methods
curl -G https://api-sandbox.payabli.com/api/v2/payment-methods \
     -H "Authorization: Bearer <token>" \
     -d limit=1 \
     -d page=1
Try it

The response returns a page of payment methods with pagination metadata:

Response
{
  "success": true,
  "message": "Payment methods retrieved successfully",
  "traceId": "0HNNN6HH5NE0R:00000014",
  "data": {
    "data": [
      {
        "paymentMethodReference": "019ff142-454b-7721-96a3-c8628b9d568f",
        "type": "bank_account",
        "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
        "ownerType": "business",
        "status": "PENDING",
        "createdAt": "2026-08-11T14:38:00.011776",
        "lastUpdated": "2026-08-11T14:38:00.011776",
        "_links": {
          "self": "/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f",
          "owner": "/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
        },
        "isDefault": false,
        "nickname": "Operating account",
        "financialInstitution": "Bank of Example",
        "accountType": "Checking",
        "accountNumber": "****6789",
        "routingNumber": "*****0021",
        "usage": [
          "deposits",
          "billing"
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "totalPages": 1,
      "totalRecords": 1,
      "pageSize": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

Update a payment method

Send a PATCH request to /v2/payment-methods/{paymentMethodReference} with only the fields you want to change. Only payment methods in PENDING status can be updated. Once a payment method is active, change it through the bank account change process instead. See the API reference for this endpoint for full documentation.

PATCH
/api/v2/payment-methods/:paymentMethodReference
curl -X PATCH https://api-sandbox.payabli.com/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "nickname": "Primary operating account",
  "usage": [
    "deposits",
    "billing"
  ]
}'
Try it

The response confirms the update:

Response
{
  "success": true,
  "message": "Payment method updated successfully",
  "traceId": "0HNNN6HH5NE2H:00000016",
  "data": {
    "paymentMethodReference": "019ff142-454b-7721-96a3-c8628b9d568f",
    "type": "bank_account",
    "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "ownerType": "business",
    "status": "PENDING",
    "createdAt": "2026-08-11T14:38:00.0117762Z",
    "lastUpdated": "2026-08-11T14:39:12.4471182Z",
    "_links": {
      "self": "/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f",
      "owner": "/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "fingerprint": "2a0c2a64d03492ba45af4d01f329f22b41513411cab7658072739d17ed570675",
    "tokenReference": "deacc32d-81eb-470b-9cff-0ad2fab87096",
    "nickname": "Primary operating account",
    "financialInstitution": "Bank of Example",
    "accountType": "Checking",
    "accountNumber": "****6789",
    "routingNumber": "*****0021",
    "usage": [
      "deposits",
      "billing"
    ]
  }
}

Deactivate a payment method

Send a DELETE request to /v2/payment-methods/{paymentMethodReference}. This is a soft delete: the payment method moves to INACTIVE and the record is kept. See the API reference for this endpoint for full documentation.

DELETE
/api/v2/payment-methods/:paymentMethodReference
curl -X DELETE https://api-sandbox.payabli.com/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f \
     -H "Authorization: Bearer <token>"
Try it

The response confirms the deactivation:

Response
{
  "success": true,
  "message": "Payment method deactivated successfully",
  "traceId": "0HNNN6HH5NE2S:0000000A",
  "data": {
    "paymentMethodReference": "019ff142-454b-7721-96a3-c8628b9d568f",
    "type": "bank_account",
    "accountOwner": "019fed1a-3d6e-75d3-a81e-cba3874b0a55",
    "ownerType": "business",
    "status": "INACTIVE",
    "createdAt": "2026-08-11T14:38:00.0117762Z",
    "lastUpdated": "2026-08-11T14:40:03.1182233Z",
    "_links": {
      "self": "/api/v2/payment-methods/019ff142-454b-7721-96a3-c8628b9d568f",
      "owner": "/api/v2/businesses/019fed1a-3d6e-75d3-a81e-cba3874b0a55"
    },
    "fingerprint": "2a0c2a64d03492ba45af4d01f329f22b41513411cab7658072739d17ed570675",
    "tokenReference": "deacc32d-81eb-470b-9cff-0ad2fab87096",
    "nickname": "Primary operating account",
    "financialInstitution": "Bank of Example",
    "accountType": "Checking",
    "accountNumber": "****6789",
    "routingNumber": "*****0021",
    "usage": [
      "deposits",
      "billing"
    ]
  }
}

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