Skip to main content
Pay requests let you generate a personalized payment link and email it directly to a customer. Kulmi Pay hosts the checkout page — your customer receives an email with a link they open to complete the payment at their convenience. You can optionally set an amount, a payment reason, and an automatic reminder. Base URL: https://app.kulmipay.com/api/v1/payment/collection/pay-requests/

​
Authentication

Authorization: Bearer <secret_key>

​
Create a pay request

Method: POST
URL: https://app.kulmipay.com/api/v1/payment/collection/pay-requests/

​
Request

​
first_name
string
required
Customer’s first name. Used in the email greeting and the checkout page.
​
last_name
string
required
Customer’s last name.
​
email
string
required
Customer’s email address. Kulmi Pay sends the payment link to this address immediately after the pay request is created.
​
currency
string
required
Currency for this pay request. One of: KES, USD, EUR, GBP.
​
amount
number
Fixed payment amount. When set, the customer cannot change the amount on the checkout page. Omit to allow the customer to enter any amount.
​
reason
string
Description of what the payment is for, for example "Invoice #1042 — web development services". Displayed on the checkout page and in the email.
​
autosend_reminder
number
default:"0"
Number of days after creation before Kulmi Pay automatically sends a reminder email to the customer. Accepted values: 0 (no reminder), 1, 2, 3, or 7. Defaults to 0.
​
card_tarrif
string
default:"BUSINESS-PAYS"
Who pays the card processing fee on this pay request. Either BUSINESS-PAYS or CUSTOMER-PAYS.

​
Response

​
detail
object
The pay request object.

​
Retrieve a pay request

Method: GET
URL: https://app.kulmipay.com/api/v1/payment/collection/pay-requests/{request_id}/ Pass the request_id from the create response as a path parameter. The response shape is identical to the create response.

​
Code examples

curl --request POST \
  --url https://app.kulmipay.com/api/v1/payment/collection/pay-requests/ \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "currency": "KES",
    "amount": 5000,
    "reason": "Invoice #1042 — web development services",
    "autosend_reminder": 3,
    "card_tarrif": "BUSINESS-PAYS"
  }'

import requests

response = requests.post(
    "https://app.kulmipay.com/api/v1/payment/collection/pay-requests/",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com",
        "currency": "KES",
        "amount": 5000,
        "reason": "Invoice #1042 — web development services",
        "autosend_reminder": 3,
        "card_tarrif": "BUSINESS-PAYS",
    },
)

data = response.json()
pay_request = data["detail"]
checkout_url = pay_request["checkout"]["url"]

​
Example response

{
  "detail": {
    "request_id": "PR_ABC123",
    "checkout": {
      "id": "d9f3a821-5b2c-4e8a-a1d4-3c7f9e2b0a14",
      "url": "https://app.kulmipay.com/checkout/d9f3a821-5b2c-4e8a-a1d4-3c7f9e2b0a14/express/",
      "amount": "5000.00",
      "currency": "KES",
      "email": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "paid": false
    },
    "payment_status": "Pending",
    "sent_status": "SENT",
    "reason": "Invoice #1042 — web development services",
    "autosend_reminder": 3,
    "autosend_reminder_datetime": "2024-04-19T08:23:11.000Z",
    "reminder_sent": false,
    "archived": false,
    "failed_details": null,
    "created_at": "2024-04-16T08:23:11.042Z",
    "updated_at": "2024-04-16T08:23:11.042Z"
  }
}
Kulmi Pay sends the payment email immediately after the pay request is created, as long as the sent_status is not FAILED. If email delivery fails, the failed_details field contains the error description.