Skip to main content
Create a payment link that can be shared with customers to collect payments. This endpoint allows you to generate customizable payment links with various options for collecting funds.

​
Overview

The Create Payment Link endpoint generates a unique URL that customers can use to make payments. You can customize the payment amount, currency, expiration date, and collect additional information from customers during the payment process.

​
Request Parameters

FieldTypeDescriptionRequired
currencystringThe currency code for the payment (e.g., “USD”)Required
expiredAtstringThe expiration date and time for the payment linkRequired
namestringThe name or title of the payment linkRequired
amountnumberThe payment amountRequired
redirectTostringURL to redirect to after successful paymentRequired
amountLockedbooleanWhether the amount is locked and cannot be changedOptional
customerPaysbooleanWhether the customer pays the processing feeOptional
customUrlPathstringCustom URL path for the payment linkOptional
dataCollectionsarrayArray of data collection fields for the payment form. Email, first name and last name are added by defaultOptional
customFieldsarrayArray of custom fields for the payment formOptional
isOpenLinkbooleanIf set to false, the payment link will expire after first useOptional
acceptedPaymentOptionsarrayArray of accepted payment methodsOptional
externalIdstringEnd user account IDOptional
cartItemsobjectList of cartItemsRequired for ecommerce checkout

​
Example Request

curl -X POST "{{LIQUIDITY_URL}}/v1/ext/collections/payment-link" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "currency": "USD",
    "expiredAt": "2024-12-31T23:59:59Z",
    "name": "Invoice Payment #12345",
    "amount": 100.00,
    "redirectTo": "https://yourwebsite.com/success",
    "amountLocked": true,
    "customerPays": false,
    "customUrlPath": "pay-invoice-12345",
    "dataCollections": ["Phone"],
    "customFields": ["Company Name", "Reference Number"],
    "isOpenLink": false,
    "acceptedPaymentOptions": ["card", "google_pay", "apple_pay", "cashapp"],
    "externalId": "acc_123456789"
  }'

​
Example Response

{
  "data": {
    "url": "https://sandbox.checkout.centryos.xyz/page/sATA3BiyVi42g3OgrD54ANNllMXtA",
    "application": {
      "id": "b837dcf1-6c68-4cbb-a01d-3ad144f80060",
      "token": "sATA3BiyVi42g3OgrD54ANNllMXtA",
      "expiredAt": "2024-12-31T23:59:59.000Z",
      "valid": true
    }
  }
}

​
Data Collection

You can collect additional information from customers during payment:
  • Default fields: Email, First Name, Last Name (automatically included)
  • Additional fields: Phone, Address, Company, etc.
  • Custom fields: Any additional information you need

​
Payment Options

Configure which payment methods to accept:
  • Card payments: Credit and debit cards
  • Bank transfers: Direct bank transfers
  • Mobile money: Mobile payment solutions
  • Single-use links: Set isOpenLink: false to expire after first payment
  • Reusable links: Set isOpenLink: true for multiple payments
  • Amount flexibility: Allow or prevent customers from modifying amounts

​
Use Cases

​
Invoice Payments

{
  "currency": "USD",
  "expiredAt": "2024-12-31T23:59:59Z",
  "name": "Invoice #INV-2024-001",
  "amount": 500.00,
  "customUrlPath": "page",
  "redirectTo": "https://yourcompany.com/payment-success",
  "amountLocked": true,
  "isOpenLink": false,
  "acceptedPaymentOptions": [
      "card"
  ],
  "customUrlPath": "pay-invoice-2024-001"
}

​
Ecommerce Checkout

{
  "currency": "USD",
  "expiredAt": "2024-12-31T23:59:59Z",
  "name": "Checkout",
  "amount": 500,
  "customUrlPath": "page",
  "redirectTo": "https://charity.org/thank-you",
  "isOpenLink": true,
  "dataCollections": [],
  "acceptedPaymentOptions": [
      "card",
      "google_pay"
  ],
  "cartItems": [
    {
        "name": "Product name",
        "description": "Product description",
        "qty": 1,
        "price": 500,
        "currency": "USD",
        "productId": "8finuherkjhgwmitujr"
    }
  ]
}
Example e-commerce payment link: PC checkout page

​
Best Practices

  1. Set appropriate expiration dates - Give customers enough time to complete payment
  2. Use descriptive names - Help customers identify what they’re paying for
  3. Always provide redirectTo - Ensure customers know where they’ll be taken after payment
  4. Collect relevant data - Only ask for information you actually need
  5. Test payment flows - Always test in sandbox before going live
  6. Monitor payment status - Set up webhooks to track payment completion
  7. Use single-use links for invoices - Set isOpenLink: false for one-time payments
  8. Use reusable links for donations - Set isOpenLink: true for ongoing campaigns

​
Integration Tips

  • Account linking: Use externalId to link payments to specific end user accounts
  • Seamless experience: Use redirectTo to provide a smooth post-payment flow
  • Webhook handling: Implement webhook processing to handle successful payments
  • Custom branding: Use customUrlPath for branded, memorable payment URLs
  • Data management: Leverage the default email/name collection for user identification

​
Common Scenarios

​
E-commerce Checkout

  • Use single-use links with locked amounts
  • Input fields for shipping info are added by default