Payment Links

A Payment Link is a unique URL generated by a business to facilitate secure and convenient online payments. It allows customers to complete a transaction without requiring access to a traditional e-commerce platform. Businesses can share the link via email, SMS, social media, or messaging platforms.

When a customer clicks on the link, they are redirected to a secure payment page where they can review the details and complete their payment. Payment links are commonly used for one-time payments, settling invoices, or collecting donations.

How long a link lives

A payment link can be paid for 30 minutes. expiresAt is optional: leave it out and the link expires 30 minutes after it is created. A later time is cut back to 30 minutes from the moment of the request, so a link never lives longer. When a link has expired, the payer sees that it is no longer valid, and you create a new one or renew it with Update Payment Link.

What the payer sees

Give the payer the url from the response, for example https://checkout.st-payup.com/payment-links/pl_.... The page asks for the card number, expiry date, CVV and the name on the card, nothing else. After the payment the payer sees the result on the page; if you passed successUrl or failureUrl, a button takes them back to your site.

Create Payment Link

POST/v1/payment-links

This endpoint creates a unique, secure payment link that merchants can send to their customers. The link provides an easy and secure method for customers to pay for goods or services via the ST Pay Payment Gateway. Merchants can use this link for both one-time and recurring payments.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Request body

Name	Type	Description
`amount` required	number (float)	The total amount to be paid by the customer, expressed in the specified currency (e.g., 100.50 USD). Example: `150.75`
`currency` required	string (ISO 4217)	The currency used for the payment, following the ISO 4217 standard (e.g., USD, EUR). Example: `USD`
`orderReference` required	string	A unique identifier for the order associated with the payment. This reference is used to track and reconcile the transaction. Example: `order_12345`
`terminalId` required	string (uuid)	A unique identifier for the terminal or merchant initiating the payment link request. It links the link to a specific merchant or terminal. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`description`	string	A brief description of the product or service being purchased. This information will be displayed to the customer when completing the payment. Example: `Premium T-Shirt`
`locale`	string	The locale setting for the payment link, determining the language and formatting of the payment page (e.g., 'en_US'). Example: `en_US`
`expiresAt`	string	The expiration date and time of the payment link, in ISO 8601 format. Optional: when omitted, the link expires 30 minutes after it is created. A later time is cut back to 30 minutes from the request. After this time the payment cannot be completed. Example: `2025-12-12T12:12:00Z`
`customer`	object

{
  "amount": 150.75,
  "currency": "USD",
  "orderReference": "order_12345",
  "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
  "description": "Premium T-Shirt",
  "locale": "en_US",
  "expiresAt": "2025-12-12T12:12:00Z",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "email": "john.doe@example.com"
  }
}

Responses

201 The payment link was successfully created. The generated link can now be shared with the customer to enable payment.

Name	Type	Description
`id`	string (uuid)	A unique identifier for the generated payment link, used for future reference in operations like status checks or cancellations. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`amount`	number (float)	The total amount to be paid by the customer, which should match the amount specified when creating the payment link. Example: `150.75`
`currency`	string	The currency in which the payment is to be made, matching the currency specified when the payment link was created. Example: `USD`
`orderReference`	string	The order reference provided during payment link creation, used for transaction tracking and reconciliation. Example: `order_12345`
`terminalId`	string (uuid)	A unique identifier for the terminal or merchant who generated the payment link, linking the link to the originating merchant or terminal. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`description`	string	A description of the product or service being paid for, which will be shown to the customer during the payment process. Example: `Premium T-Shirt`
`locale`	string	The locale setting that determines the language and format of the payment page (e.g., 'en_US'). Example: `en_US`
`expiresAt`	string	The expiration date and time for the payment link: 30 minutes after it was created unless it was renewed. After this time, the link is invalid. Example: `2025-12-12T12:12:00Z`
`customer`	object
`customer.id`	string (uuid)	A unique identifier for the customer associated with the payment link. Example: `171f8b37-7401-4e59-b99a-2b414b4e6348`
`customer.firstName`	string	The first name of the customer, which helps identify them during the payment process. Example: `John`
`customer.lastName`	string	The last name of the customer. Example: `Doe`
`customer.phone`	string	The phone number of the customer in E.164 format, used for notifications if provided. Example: `+1234567890`
`customer.email`	string	The email address used for sending the payment link to the customer. Example: `john.doe@example.com`
`createdAt`	string	The timestamp when the payment link was generated, indicating when the customer was given the option to complete payment. Example: `2025-01-08T10:00:00Z`
`status`	string	The current status of the payment link, which reflects its lifecycle (e.g., whether it has been viewed, expired, or paid). One of: `active`, `viewed`, `attempted`, `expired`, `cancelled`, `paid`. Example: `active`

{
  "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
  "amount": 150.75,
  "currency": "USD",
  "orderReference": "order_12345",
  "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
  "description": "Premium T-Shirt",
  "locale": "en_US",
  "expiresAt": "2025-12-12T12:12:00Z",
  "customer": {
    "id": "171f8b37-7401-4e59-b99a-2b414b4e6348",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "email": "john.doe@example.com"
  },
  "createdAt": "2025-01-08T10:00:00Z",
  "status": "active"
}

400 The request payload was invalid, missing required fields (e.g., amount, currency, email), or contained incorrect data.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

422 The request contains invalid or incomplete data. Ensure that all mandatory fields are correctly provided.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request. The payment link could not be created due to an internal issue.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Retrieve Payment Links

GET/v1/payment-links

This endpoint retrieves a list of payment links based on various filters, such as date range and status. It supports pagination to retrieve large sets of results.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`from`	query	string (date)	The start date of the payment links to be retrieved, in ISO 8601 format (e.g., '2024-01-01').
`to`	query	string (date)	The end date of the payment links to be retrieved, in ISO 8601 format (e.g., '2024-12-31').
`status`	query	string	The status of the payment links to be retrieved (e.g., 'active', 'paid', 'expired'). One of: `active`, `viewed`, `attempted`, `expired`, `cancelled`, `paid`.
`page`	query	integer	The page number for pagination. Defaults to 1 if not provided. Example: `1`
`size`	query	integer	The number of items per page for pagination. Defaults to 20 if not provided. Example: `20`

Responses

200 A list of payment links matching the specified criteria, along with pagination details.

Name	Type	Description
`total`	integer	The total number of payment links matching the query criteria. Example: `100`
`data`	object[]
`data[].id`	string (uuid)	A unique identifier for the generated payment link, used for future reference in operations like status checks or cancellations. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`data[].amount`	number (float)	The total amount to be paid by the customer, which should match the amount specified when creating the payment link. Example: `150.75`
`data[].currency`	string	The currency in which the payment is to be made, matching the currency specified when the payment link was created. Example: `USD`
`data[].orderReference`	string	The order reference provided during payment link creation, used for transaction tracking and reconciliation. Example: `order_12345`
`data[].terminalId`	string (uuid)	A unique identifier for the terminal or merchant who generated the payment link, linking the link to the originating merchant or terminal. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`data[].description`	string	A description of the product or service being paid for, which will be shown to the customer during the payment process. Example: `Premium T-Shirt`
`data[].locale`	string	The locale setting that determines the language and format of the payment page (e.g., 'en_US'). Example: `en_US`
`data[].expiresAt`	string	The expiration date and time for the payment link: 30 minutes after it was created unless it was renewed. After this time, the link is invalid. Example: `2025-12-12T12:12:00Z`
`data[].customer`	object
`data[].customer.id`	string (uuid)	A unique identifier for the customer associated with the payment link. Example: `171f8b37-7401-4e59-b99a-2b414b4e6348`
`data[].customer.firstName`	string	The first name of the customer, which helps identify them during the payment process. Example: `John`
`data[].customer.lastName`	string	The last name of the customer. Example: `Doe`
`data[].customer.phone`	string	The phone number of the customer in E.164 format, used for notifications if provided. Example: `+1234567890`
`data[].customer.email`	string	The email address used for sending the payment link to the customer. Example: `john.doe@example.com`
`data[].createdAt`	string	The timestamp when the payment link was generated, indicating when the customer was given the option to complete payment. Example: `2025-01-08T10:00:00Z`
`data[].status`	string	The current status of the payment link, which reflects its lifecycle (e.g., whether it has been viewed, expired, or paid). One of: `active`, `viewed`, `attempted`, `expired`, `cancelled`, `paid`. Example: `active`

{
  "total": 100,
  "data": [
    {
      "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
      "amount": 150.75,
      "currency": "USD",
      "orderReference": "order_12345",
      "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
      "description": "Premium T-Shirt",
      "locale": "en_US",
      "expiresAt": "2025-12-12T12:12:00Z",
      "customer": {
        "id": "171f8b37-7401-4e59-b99a-2b414b4e6348",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+1234567890",
        "email": "john.doe@example.com"
      },
      "createdAt": "2025-01-08T10:00:00Z",
      "status": "active"
    }
  ]
}

400 The request was invalid, such as missing required query parameters.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Retrieve Payment Link

GET/v1/payment-links/{paymentLinkId}

This endpoint retrieves the details of a payment link by its unique identifier. Merchants can use this to check the status or view the details of a previously generated payment link.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`paymentLinkId` required	path	string (uuid)	The unique identifier of the payment link to be retrieved.

Responses

200 The payment link details were successfully retrieved.

Name	Type	Description
`id`	string (uuid)	A unique identifier for the generated payment link, used for future reference in operations like status checks or cancellations. Example: `2d120e98-0521-4278-9683-b23e4b16ad14`
`amount`	number (float)	The total amount to be paid by the customer, which should match the amount specified when creating the payment link. Example: `150.75`
`currency`	string	The currency in which the payment is to be made, matching the currency specified when the payment link was created. Example: `USD`
`orderReference`	string	The order reference provided during payment link creation, used for transaction tracking and reconciliation. Example: `order_12345`
`terminalId`	string (uuid)	A unique identifier for the terminal or merchant who generated the payment link, linking the link to the originating merchant or terminal. Example: `f6f0b462-570f-4027-b9b3-d345efca67c8`
`description`	string	A description of the product or service being paid for, which will be shown to the customer during the payment process. Example: `Premium T-Shirt`
`locale`	string	The locale setting that determines the language and format of the payment page (e.g., 'en_US'). Example: `en_US`
`expiresAt`	string	The expiration date and time for the payment link: 30 minutes after it was created unless it was renewed. After this time, the link is invalid. Example: `2025-12-12T12:12:00Z`
`customer`	object
`customer.id`	string (uuid)	A unique identifier for the customer associated with the payment link. Example: `171f8b37-7401-4e59-b99a-2b414b4e6348`
`customer.firstName`	string	The first name of the customer, which helps identify them during the payment process. Example: `John`
`customer.lastName`	string	The last name of the customer. Example: `Doe`
`customer.phone`	string	The phone number of the customer in E.164 format, used for notifications if provided. Example: `+1234567890`
`customer.email`	string	The email address used for sending the payment link to the customer. Example: `john.doe@example.com`
`createdAt`	string	The timestamp when the payment link was generated, indicating when the customer was given the option to complete payment. Example: `2025-01-08T10:00:00Z`
`status`	string	The current status of the payment link, which reflects its lifecycle (e.g., whether it has been viewed, expired, or paid). One of: `active`, `viewed`, `attempted`, `expired`, `cancelled`, `paid`. Example: `active`

{
  "id": "2d120e98-0521-4278-9683-b23e4b16ad14",
  "amount": 150.75,
  "currency": "USD",
  "orderReference": "order_12345",
  "terminalId": "f6f0b462-570f-4027-b9b3-d345efca67c8",
  "description": "Premium T-Shirt",
  "locale": "en_US",
  "expiresAt": "2025-12-12T12:12:00Z",
  "customer": {
    "id": "171f8b37-7401-4e59-b99a-2b414b4e6348",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890",
    "email": "john.doe@example.com"
  },
  "createdAt": "2025-01-08T10:00:00Z",
  "status": "active"
}

400 The request was invalid or the payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404 The specified payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Update Payment Link

PATCH/v1/payment-links/{paymentLinkId}

This endpoint updates the expiration date of a previously generated payment link. Merchants can use this endpoint to extend or modify the expiration of the payment link if needed.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`paymentLinkId` required	path	string (uuid)	The unique identifier of the payment link to be updated.

Request body

Name	Type	Description
`expiresAt` required	string	The new expiration date and time of the payment link in ISO 8601 format. A link can be valid for at most 30 minutes from the moment of the request; a later time is cut back to that.

{
  "expiresAt": "string"
}

Responses

204 The expiration date of the payment link was successfully updated. No content is returned.

400 The request was invalid or the payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404 The specified payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Cancel Payment Link

POST/v1/payment-links/{paymentLinkId}/cancel

This endpoint cancels a previously generated payment link, making it no longer valid for payment. Merchants can use this endpoint if they wish to invalidate the payment link before its expiration.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`paymentLinkId` required	path	string (uuid)	The unique identifier of the payment link to be cancelled.

Responses

204 Payment link was cancelled successfully. The link is now invalid.

400 The request was invalid or the payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

401 Unauthorized access. The request was not properly authenticated, or the provided credentials are invalid.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

404 The specified payment link ID was not found.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

500 A server error occurred while processing the request.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Payment Link Statistics

GET/v1/payment-links/statistics

Totals of your payment links by status. currency is required.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`currency` required	query	string	Example: `USD`

Responses

200 One entry per status.

Name	Type	Description
`items`	object[]
`items[].status`	string	Example: `active`
`items[].totalAmount`	number (float)	Example: `250.5`
`items[].totalCount`	integer	Example: `5`
`items[].currency`	string	Example: `USD`

{
  "items": [
    {
      "status": "active",
      "totalAmount": 250.5,
      "totalCount": 5,
      "currency": "USD"
    }
  ]
}

401 Missing or invalid API key.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`

Payment Link Customers

GET/v1/payment-links/customers

The people your payment links were issued to (the customer of a link), newest scope first, as a standard list.

https://api-stage.st-payup.com Stage, for development and testing
https://api.st-payup.com Production, for live transactions (available once your company is approved)

Parameters

Name	In	Type	Description
`page`	query	integer	Example: `1`
`size`	query	integer	Example: `20`

Responses

200 A page of customers.

Name	Type	Description
`data`	object[]
`data[].id`	string (uuid)
`data[].firstName`	string
`data[].lastName`	string
`data[].email`	string (email)
`data[].phone`	string
`page`	integer
`size`	integer
`total`	integer

{
  "data": [
    {
      "id": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phone": "string"
    }
  ],
  "page": 0,
  "size": 0,
  "total": 0
}

401 Missing or invalid API key.

Name	Type	Description
`message`	string	Example: `An error occurred while processing your request.`
`code`	integer	Example: `1012`