Payment routing

Multi-channel Payments API

Register multiple tills, paybills, bank channels, or crypto destinations and select the intended channel for each payment.

One merchant, multiple channels

Each channel receives a generated PAYL alias. Channel records remain isolated to the authenticated merchant, and API keys require the matching channels scope.

Create

Select

Pass a channel's ID, PAYL alias, or number as channelId on STK Push.

Control

Mark a channel inactive to stop new payments without deleting its history.

List channels

GET/api/v1/merchants/api/channels

List payment channels

Returns every channel owned by the merchant. Use the project-scoped route to return channels for one project.

No request body

Use the Authorization header and query string parameters shown in the endpoint path.

Responsejson

1{2  "channels": [3    {4      "id": "665f4c1b9a8d2e001f2a1111",5      "alias": "PAYL-XJ7K2P",6      "name": "Main paybill",7      "type": "PAYBILL",8      "number": "123456",9      "accountNumber": "STORE-01",10      "status": "ACTIVE"11    }12  ]13}

Code examples

GET /api/v1/merchants/api/channelsbash

1curl -X GET https://api.paylorke.com/api/v1/merchants/api/channels \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json"

Create channels

POST/api/v1/merchants/api/channels

Create a payment channel

Adds another independently addressable channel. Required fields are name, type (TILL, PAYBILL, BANK, or CRYPTO), and number. TILL and PAYBILL numbers must be digits only; BANK channels also take bankName and accountNumber; CRYPTO channels take a TRON (TRC20) address as the number. The response includes the generated PAYL alias used when routing payments.

Request bodyjson

1{2  "name": "Westlands till",3  "type": "TILL",4  "number": "543210",5  "externalReference": "location-westlands",6  "metadata": { "location": "Westlands" }7}

Responsejson

1{2  "message": "Channel created successfully",3  "channel": {4    "id": "665f4c1b9a8d2e001f2a2222",5    "alias": "PAYL-7N4KQP",6    "name": "Westlands till",7    "type": "TILL",8    "number": "543210",9    "status": "ACTIVE"10  }11}

Code examples

POST /api/v1/merchants/api/channelsbash

1curl -X POST https://api.paylorke.com/api/v1/merchants/api/channels \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "name": "Westlands till",6  "type": "TILL",7  "number": "543210",8  "externalReference": "location-westlands",9  "metadata": { "location": "Westlands" }10}'

Update or delete channels

PATCH/api/v1/merchants/api/channels/:channelId

Update a payment channel

Updates mutable channel details or changes whether the channel can receive new routed payments. Accepts name, status, bankName, accountNumber, externalUserId, externalReference, and metadata. A channel's type and number are immutable — delete and recreate the channel to change them.

Request bodyjson

1{2  "name": "Westlands flagship till",3  "status": "ACTIVE"4}

Responsejson

1{2  "message": "Channel updated successfully",3  "channel": {4    "id": "665f4c1b9a8d2e001f2a2222",5    "alias": "PAYL-7N4KQP",6    "name": "Westlands flagship till",7    "status": "ACTIVE"8  }9}

Code examples

PATCH /api/v1/merchants/api/channels/:channelIdbash

1curl -X PATCH https://api.paylorke.com/api/v1/merchants/api/channels/:channelId \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "name": "Westlands flagship till",6  "status": "ACTIVE"7}'

DELETE/api/v1/merchants/api/channels/:channelId

Delete a payment channel

Permanently removes a channel owned by the authenticated merchant.

No request body

Use the Authorization header and query string parameters shown in the endpoint path.

Responsejson

1{2  "message": "Channel deleted successfully"3}

Code examples

DELETE /api/v1/merchants/api/channels/:channelIdbash

1curl -X DELETE https://api.paylorke.com/api/v1/merchants/api/channels/:channelId \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json"

Route a payment

Set channelId on POST /api/v1/merchants/payments/stk-push or /api/v1/merchants/payments/b2b-express. Despite the field name, it accepts the channel ID, generated PAYL alias, or configured channel number.

Use a stable PAYL-XXXXXX alias in your integration. The API verifies that the selected channel is active and belongs to the authenticated merchant before initiating payment.

Crypto is routed differently. A CRYPTO channel is selected with cryptoId on the crypto endpoints, and that field accepts the channel ID only — not the alias or the TRON address. Omitting it picks one of your active crypto channels. See Crypto Payments.

Project-scoped channels

For project API keys, use /api/v1/merchants/api/projects/:projectId/channels. List, create, update, and delete operations are restricted to that project.

Project payment routes resolve channels from the same project and can fall back to merchant-level channels.