Skip to content

createLink

Create a payment link for a single recipient.

Request

POST /api/v2/createLink

Headers

Header Required Description
token Yes Your API Key
Content-Type Yes application/json

Body Parameters

Field Type Required Description
amount number Yes Payment amount in EUR (must be > 0)
recipient_note string No Note for identifying the payment (e.g., invoice number)
callback_url string No URL or index for browser redirect after payment. See Callbacks
payment_endpoint string No Webhook URL(s) for this link. Accepts a URL, index, or comma-separated mix. See Webhooks
cancellable boolean No Whether customer can cancel. Default: true
bank_transfer string No Enable bank transfer payment method ("true" / "false")
is_encryption string No Enable encrypted webhook payloads ("true" / "false")
encryption_key string No Custom AES-256-CBC key for webhook encryption
bank_statement_description string No Text shown on customer's bank statement
is_qr_link string No Generate a QR code image URL ("true" / "false")

callback_url Options

The callback_url field accepts:

  • A full URL: "https://yoursite.com/payment/done" — customer redirects here
  • An index (string): "0", "1", etc. — uses the Nth URL from your account's configured callback_urls list
  • Omitted: Customer sees SecPaid's default success/cancel page

Response

Success (ResponseCode: 1)

{
  "data": {
    "is_cancellation": "No",
    "user_id": "b44c4429-4a7b-4e27-85af-c1c2f43f4ffe",
    "amount": 25,
    "recipient_note": "Test regular link",
    "status": "Unused",
    "paymentEndpoint": "https://google.com",
    "callback_url": "https://google.com",
    "servicefee": "1.0",
    "recipients": null,
    "is_split_link": "false",
    "split_type": "normal",
    "bank_transfer": "true",
    "is_qr_link": "false",
    "payment_config": "",
    "bank_statement_description": "",
    "created_at": "2026-05-20 11:19:48",
    "id": 99290,
    "pay_link": "https://app.secpaid.com/payment?link_id=OTkyOTA=",
    "qr_img": "https://quickchart.io/chart?chl=https://app.secpaid.com/payment?link_id=OTkyOTA=&chs=300x300&cht=qr",
    "transaction_type": "Basic"
  },
  "ResponseCode": 1,
  "ResponseMsg": "Link has been created successfully",
  "Result": "True",
  "ServerTime": "CEST"
}

Response Fields

Field Type Description
id integer Unique link ID
pay_link string Payment URL to send to customer
qr_img string QR code image URL encoding the pay_link
amount number Payment amount in EUR
status string Always "Unused" on creation
transaction_type string "Basic" for regular links
is_cancellation string "No" = customer can cancel, "Yes" = cannot cancel
recipient_note string Your reference note
callback_url string Configured redirect URL(s)
paymentEndpoint string Configured webhook URL(s)
servicefee string Platform fee percentage for this link
bank_transfer string Whether bank transfer is available
is_split_link string "false" for regular links
split_type string "normal" for regular links
bank_statement_description string Text on customer's bank statement
is_qr_link string Whether QR code link
payment_config string Payment configuration
created_at string Creation timestamp (UTC)

Error (ResponseCode: 0)

{
  "ResponseCode": 0,
  "ResponseMsg": "Please enter amount",
  "Result": "False",
  "ServerTime": "CEST"
}

Common errors:

ResponseMsg Cause
Please enter token Missing token header
No user found with the provided API key. Invalid API key
Please enter amount Missing amount field
Amount should not be zero or negative number amount ≤ 0

Examples

curl -X POST https://app.secpaid.com/api/v2/createLink \
  -H "Content-Type: application/json" \
  -H "token: YOUR_API_KEY" \
  -d '{
    "amount": 49.99,
    "recipient_note": "Invoice #1234",
    "callback_url": "https://yoursite.com/payment/done",
    "cancellable": true
  }'

const response = await fetch("https://app.secpaid.com/api/v2/createLink", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "token": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    amount: 49.99,
    recipient_note: "Invoice #1234",
    callback_url: "https://yoursite.com/payment/done",
    cancellable: true
  })
});

const { data } = await response.json();
// data.pay_link → send to customer

$response = Http::withHeaders([
    'token' => 'YOUR_API_KEY',
])->post('https://app.secpaid.com/api/v2/createLink', [
    'amount' => 49.99,
    'recipient_note' => 'Invoice #1234',
    'callback_url' => 'https://yoursite.com/payment/done',
    'cancellable' => true,
]);

$payLink = $response->json()['data']['pay_link'];

Notes

  • The pay_link URL is what you send to your customer
  • link_id in the URL is base64_encode(id) — e.g., link ID 99290 becomes OTkyOTA=
  • cancellable defaults to true (customer can cancel), hence is_cancellation: "No" in response means cancellation is allowed
  • The qr_img field contains a ready-to-use QR code image URL
  • bank_transfer: "true" means bank transfer payment method is available
  • servicefee shows the platform fee percentage that will be deducted from this link
  • is_encryption: "true" enables AES-256-CBC encrypted webhook payloads
  • bank_statement_description appears on the customer's card/bank statement