Payment Links

A powerful feature for upselling your products. Quickly generate a payment request with a desired amount and send the link to your customer to initiate payment.

Overview

You can create a Payment Link via the Merchant Console or through the API. To create a Payment Link, your account must have the feature enabled. If you’re unsure whether it’s enabled, please reach out to your merchant manager for confirmation.

API Endpoint

POST /api/v3/paymentlinks

Request Parameters

Field	Required	Description
`country`	Yes	2-letter ISO country code, e.g GH, BJ, MA
`currency`	Yes	3-letter ISO currency code, e.g XOF, USD
`amount`	Yes	e.g 12.34
`description`	Yes	Product description
`orderCommand`	No	Enum values: AUTHORIZE (fund authorization) or CHARGE (auth and capture, default value)
`orderId`	No	Merchant order’s ID.
`validityPeriod`	No	(d,h,m) e.g “1,2,3” means the payment link will expire in 1 day, 2 hours and 3 minutes. Default: 90 days from creation.
`customerId`	No	Customer’s ID. If the ID is not in the system, a new customer will be created.
`customerName`	No	Customer’s name.
`customerEmail`	Optional	Customer’s email. Required if “sendEmail” is true; payment reminders will be sent here.
`city`	No	Customer’s city
`state`	No	Customer’s state/province
`addressLine`	No	Customer’s address
`addressLine2`	No	Customer’s street number
`document`	No	Customer’s document ID, e.g., tax ID
`postalCode`	No	Customer’s postal code
`phoneNumber`	No	Customer’s phone number
`birthday`	No	Customer’s birthday, in yyyy-MM-dd format
`paymentMethod`	No	Enum values for the payment method (e.g., CREDIT_CARD, MTN). Contact your account manager for available methods.
`language`	No	2-letter language name for the payment page (e.g., en, fr, cn)
`callbackUrl`	No	URL to receive server-to-server notifications.
`returnUrl`	No	URL to redirect the customer to after payment completion.
`sendEmail`	No	Send payment reminders to the customer (true or false).

Example Request

{
  "country": "ZA",
  "currency": "ZAR",
  "amount": "1.00",
  "description": "Sample Goods",
  "orderCommand": "CHARGE",
  "orderId": "order-12345"
}

Response Parameters

Field	Description
`token`	The ID of the payment link, e.g LINK352100251GE26
`url`	The entry point of the payment; send this URL to the customer
`merchantName`	The name of the merchant.
`status`	Enum value, the status of the payment link (ACTIVE, DISABLED, EXPIRED)
`created`	The creation date, e.g "2025-02-27T05:37:31Z"
`lastModified`	The last modified date, e.g "2025-02-27T05:37:31Z"
`expirationDate`	Expiration date in UTC timezone, format: yyyy-MM-ddTHH:mm:ssZ. E.g "2025-05-28T00:00:00Z"
`createdBy`	API user that created the payment link.

Example Response

{
    "token": "LINK352100251GE26",
    "url": "https://sandbox.cyclepay.net/pwthree/paybylink/LINK352100251GE26",
    "merchantName": "CycleDemo",
    "country": "ZA",
    "currency": "ZAR",
    "amount": 1.00,
    "description": "Sample Goods",
    "expirationDate": "2025-05-28T00:00:00Z",
    "created": "2025-02-27T05:37:31Z",
    "lastModified": "2025-02-27T05:37:31Z",
    "status": "ACTIVE",
    "orderCommand": "CHARGE",
    "orderId": "order-12345",
    "createdBy": "cycle-api-caller"
}

Example Error Response

{
    "requestId": "be4c37c1-fec2-42b9-a6b3-68f4102a3de1",
    "errorCode": "validation_error",
    "message": "[amount] amount is required "
}

Recurring Payments

Client-Side Encryption