Payment Links

Create shareable payment links for collecting payments.

Create Payment Link

Create a new payment link.

Endpoint: POST /v1/pay/payment-links

Authentication: Required

Request Body:

Field	Type	Required	Description
`title`	string	Yes	Payment link title
`description`	string	No	Payment link description
`amount`	string	Yes	Fixed amount or `"0.00"` for variable amount
`currency`	string	Yes	Currency code (e.g., `GMD`)
`is_variable_amount`	boolean	No	Whether customers can specify their own amount (default: `false`)
`min_amount`	string	No	Minimum amount for variable-amount links
`max_amount`	string	No	Maximum amount for variable-amount links
`expiration_date`	string	No	Optional expiration date (ISO 8601)
`max_usage_count`	integer	No	Maximum number of times this link can be used
`success_url`	string	No	URL to redirect to after successful payment
`failure_url`	string	No	URL to redirect to after failed payment
`collect_customer_info`	boolean	No	Collect customer information (default: `false`)
`custom_fields`	array	No	Custom fields to collect from customers
`metadata`	object	No	Custom metadata (key-value pairs)

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "pl_abc123",
    "organization_id": "org_xyz789",
    "title": "Product Purchase",
    "description": "Payment for premium product",
    "amount": "500.00",
    "currency": "GMD",
    "is_variable_amount": false,
    "payment_url": "https://pay.jokoor.com/pay/pl_abc123",
    "success_url": "https://example.com/thank-you",
    "failure_url": "https://example.com/payment-failed",
    "status": "active",
    "collect_customer_info": false,
    "usage_count": 0,
    "mode": "test",
    "livemode": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

TIP

Payment URL: The payment_url is the hosted payment page where your customers complete their payment. Share this URL with customers via email, SMS, social media, QR codes, or embed it on your website. The hosted page handles everything - payment method selection, customer info collection, and payment processing.

TIP

Variable Amount Payment Links: Set is_variable_amount: true and optionally set min_amount and max_amount to allow customers to specify their own payment amount within a range.

Get Payment Link

Get details of a specific payment link.

Endpoint: GET /v1/pay/payment-links/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "pl_abc123",
    "organization_id": "org_xyz789",
    "title": "Product Purchase",
    "description": "Payment for premium product",
    "amount": "500.00",
    "currency": "GMD",
    "is_variable_amount": false,
    "min_amount": null,
    "max_amount": null,
    "expiration_date": null,
    "max_usage_count": null,
    "usage_count": 5,
    "payment_url": "https://pay.jokoor.com/pay/pl_abc123",
    "success_url": "https://example.com/thank-you",
    "failure_url": "https://example.com/payment-failed",
    "status": "active",
    "collect_customer_info": false,
    "custom_fields": [],
    "metadata": {},
    "mode": "test",
    "livemode": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

List Payment Links

Get a paginated list of payment links.

Endpoint: GET /v1/pay/payment-links

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status (`active`, `inactive`)

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "items": [
      {
        "id": "pl_abc123",
        "title": "Product Purchase",
        "amount": "500.00",
        "currency": "GMD",
        "payment_url": "https://pay.jokoor.com/pay/pl_abc123",
        "status": "active",
        "usage_count": 5,
        "livemode": false,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}

Update Payment Link

Update an existing payment link.

Endpoint: PUT /v1/pay/payment-links/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`title`	string	No	Payment link title
`description`	string	No	Payment link description
`expiration_date`	string	No	Expiration date (ISO 8601)
`max_usage_count`	integer	No	Maximum number of uses
`success_url`	string	No	Success redirect URL
`failure_url`	string	No	Failure redirect URL
`status`	string	No	Status (`active`, `inactive`)
`collect_customer_info`	boolean	No	Whether to collect customer information
`custom_fields`	array	No	Custom fields to collect
`metadata`	object	No	Custom metadata

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "pl_abc123",
    "title": "Updated Product Purchase",
    "status": "inactive",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Delete Payment Link

Delete a payment link.

Endpoint: DELETE /v1/pay/payment-links/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (204): No content

Payment Links

Create Payment Link#

Get Payment Link#

List Payment Links#

Update Payment Link#

Delete Payment Link#

Create Payment Link

Get Payment Link

List Payment Links

Update Payment Link

Delete Payment Link