Global Payments

Global custodial payments.

Use Global Payments for supported provider rails, custodial wallet balances, withdrawals, payment links, callbacks, and FX display.

Discover providers

Paylor supports a growing set of provider rails across markets. Always call GET /global/providers and drive your UI from the response — never hardcode which rails, countries, currencies, or channels exist.

Discover, don't hardcode

Read the enabled rails, their currencies, amount limits, and live status from the providers endpoint at runtime.

Capabilities drive the UI

Each rail declares what it supports — collect, disburse, mobile money, bank, card. Render only the flows a rail exposes.

Two collection flows

Each rail is either PUSH (prompt on the payer's phone, needs msisdn) or REDIRECT (hosted checkout, needs customerEmail). Read collectionFlow per rail.

GET/api/v1/global/providers

List providers

Returns the provider rails currently enabled for the merchant and their supported capabilities. Use this to drive your UI — never hardcode which rails, countries, currencies, or channels exist.

No request body

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

Responsejson

1{2  "success": true,3  "providers": [4    {5      "rail": "<RAIL_CODE>",6      "displayName": "<Provider display name>",7      "country": "KE",8      "currencies": ["KES"],9      "collectionFlow": "PUSH",10      "minAmount": 1,11      "maxAmount": 250000,12      "live": true,13      "capabilities": {14        "collect": true,15        "disburse": true,16        "categories": ["MOBILE_MONEY", "BANK"],17        "disbursementChannels": ["MOBILE_MONEY", "BANK"]18      }19    }20  ]21}

Code examples

GET /api/v1/global/providersbash

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

Use the rail code returned here wherever the examples below show <RAIL_CODE>. Amount limits (minAmount/maxAmount) and live status also come from this endpoint — validate against them before submitting.

Collections

Create an inbound collection against an enabled rail. Paylor credits the wallet after the provider callback is received and reconciled. The request differs by the rail's collectionFlow.

POST/api/v1/global/collections

Create collection (push rail)

Create an inbound collection on a push rail (collectionFlow=PUSH): the payer approves a prompt on their phone. Wallet credit happens after Paylor receives and reconciles the provider callback.

Request bodyjson

1{2  "rail": "<RAIL_CODE>",3  "msisdn": "0712345678",4  "amount": 1500,5  "currency": "KES",6  "description": "Invoice INV-1042"7}

Responsejson

1{2  "success": true,3  "message": "Collection initiated",4  "collection": {5    "reference": "GC-1780000000000-A9X2K",6    "status": "PENDING",7    "amount": 1500,8    "fee": 37.59  }10}

Code examples

POST /api/v1/global/collectionsbash

1curl -X POST https://api.paylorke.com/api/v1/api/v1/global/collections \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "rail": "<RAIL_CODE>",6  "msisdn": "0712345678",7  "amount": 1500,8  "currency": "KES",9  "description": "Invoice INV-1042"10}'

POST/api/v1/global/collections

Create collection (redirect rail)

For rails with collectionFlow=REDIRECT, send customerEmail instead of msisdn; the response includes an authorizationUrl. Redirect the payer there to pay by card or bank; the wallet is credited after the provider confirms and settles. Check each rail's collectionFlow from GET /global/providers.

Request bodyjson

1{2  "rail": "<RAIL_CODE>",3  "customerEmail": "[email protected]",4  "amount": 1500,5  "currency": "KES",6  "callbackReturnUrl": "https://yourapp.com/return"7}

Responsejson

1{2  "success": true,3  "message": "Redirect the payer to complete payment",4  "collection": {5    "reference": "GC-1780000000000-B7Q3M",6    "status": "PENDING",7    "amount": 1500,8    "fee": 37.59  },10  "authorizationUrl": "https://checkout.example.com/xxxxxx"11}

Code examples

POST /api/v1/global/collectionsbash

1curl -X POST https://api.paylorke.com/api/v1/api/v1/global/collections \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "rail": "<RAIL_CODE>",6  "customerEmail": "[email protected]",7  "amount": 1500,8  "currency": "KES",9  "callbackReturnUrl": "https://yourapp.com/return"10}'

Withdrawals

Withdrawals move available Global Wallet funds to a destination channel the rail supports. Add your own authorization step before submitting withdrawal requests.

RailA rail with disburse: true from GET /global/providers.

ChannelOne of the rail's disbursementChannels (e.g. mobile money or bank).

DestinationBank details for bank withdrawals, or operator and phone number for mobile money withdrawals.

POST/api/v1/global/disbursements

Withdraw funds

Create an outbound withdrawal from available Global Wallet funds to a channel the selected rail supports (read disbursementChannels from GET /global/providers).

Request bodyjson

1{2  "rail": "<RAIL_CODE>",3  "channel": "MOBILE_MONEY",4  "operator": "M-Pesa",5  "payeeMsisdn": "0712345678",6  "amount": 1000,7  "currency": "KES"8}

Responsejson

1{2  "success": true,3  "message": "Disbursement requested",4  "disbursement": {5    "reference": "GD-1780000000000-P2Q8Z",6    "status": "PROCESSING",7    "amount": 1000,8    "fee": 109  }10}

Code examples

POST /api/v1/global/disbursementsbash

1curl -X POST https://api.paylorke.com/api/v1/api/v1/global/disbursements \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "rail": "<RAIL_CODE>",6  "channel": "MOBILE_MONEY",7  "operator": "M-Pesa",8  "payeeMsisdn": "0712345678",9  "amount": 1000,10  "currency": "KES"11}'

Bank withdrawal bodyjson

1{2  "rail": "<RAIL_CODE>",3  "channel": "BANK",4  "bankCode": "11",5  "accountNumber": "0123456789",6  "accountName": "Acme Ltd",7  "amount": 1000,8  "currency": "KES"9}

Global Wallet

Provider collections, fees, holds, and withdrawals are ledgered in the merchant Global Wallet.

GET/api/v1/global/wallet

Read Global Wallet

Read available, pending, held, collected, and disbursed balances for the merchant Global Wallet.

No request body

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

Responsejson

1{2  "success": true,3  "wallet": {4    "currency": "KES",5    "availableBalance": 24000,6    "pendingBalance": 0,7    "heldBalance": 1000,8    "totalCollected": 48000,9    "totalDisbursed": 2300010  }11}

Code examples

GET /api/v1/global/walletbash

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

FX rates

Use live FX rates for dashboard display conversion. Ledger posting still uses the transaction currency and provider settlement records.

GET/api/v1/global/fx/rates?base=KES

Fetch FX rates

Fetch supported currency rates for display conversion in the Global dashboard.

No request body

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

Responsejson

1{2  "success": true,3  "rates": {4    "base": "KES",5    "rates": {6      "KES": 1,7      "TZS": 20.128    },9    "supportedCurrencies": ["TZS", "KES"],10    "fetchedAt": "2026-06-29T18:10:00.000Z"11  }12}

Code examples

GET /api/v1/global/fx/ratesbash

1curl -X GET https://api.paylorke.com/api/v1/api/v1/global/fx/rates?base=KES \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json"

Payment links

Payment links are hosted payer-facing collection flows managed through Global Payments.

POST/api/v1/global/payment-links

Create payment link

Create a hosted Global Payment link for payer-facing collections.

Request bodyjson

1{2  "title": "Invoice INV-1042",3  "amount": 1500,4  "currency": "KES",5  "rail": "<RAIL_CODE>",6  "description": "Invoice payment"7}

Responsejson

1{2  "success": true,3  "paymentLink": {4    "slug": "inv-1042-a9x2k",5    "url": "https://global.paylorke.com/pay/inv-1042-a9x2k",6    "status": "ACTIVE"7  }8}

Code examples

POST /api/v1/global/payment-linksbash

1curl -X POST https://api.paylorke.com/api/v1/api/v1/global/payment-links \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5  "title": "Invoice INV-1042",6  "amount": 1500,7  "currency": "KES",8  "rail": "<RAIL_CODE>",9  "description": "Invoice payment"10}'

GET/api/v1/global/pay/:slug/status/:reference

Check hosted payment status

Read payer-facing payment status after a hosted payment is initiated.

No request body

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

Responsejson

1{2  "success": true,3  "payment": {4    "reference": "GC-1780000000000-A9X2K",5    "status": "PENDING",6    "amount": 1500,7    "currency": "KES"8  }9}

Code examples

GET /api/v1/global/pay/:slug/status/:referencebash

1curl -X GET https://api.paylorke.com/api/v1/api/v1/global/pay/:slug/status/:reference \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json"