Data Schemas¶

This page describes the core data structures returned by the V2 API.

Link Object¶

Returned by createLink, createSplitLink, getMyUnusedLinks, and getMyUsedLinks.

{
    "linktopay_id": "integer",
    "user_id": "string",
    "amount": "double",
    "recipient_note": "string",
    "status": "Unused | Used",
    "is_cancelled": "No | Yes",
    "paymentEndpoint": "string",
    "callback_url": "string",
    "is_split_link": "false | true",
    "split_type": "normal | absolute",
    "is_qr_link": "false | true",
    "bank_transfer": "false | true",
    "servicefee": "double",
    "recipients": "json",
    "created_at": "datetime",
    "transaction_type": "Basic | Split | Personal QR",
    "pay_link": "string",
    "qr_img": "string"
}

Field	Description
`linktopay_id`	Unique link identifier
`user_id`	ID of the user who created the link
`amount`	Payment amount in EUR
`recipient_note`	Description shown to the payer
`status`	`Unused` until paid; `Used` after a successful payment
`is_cancelled`	Whether the link has been cancelled
`paymentEndpoint`	Webhook URL that receives payment events
`callback_url`	Redirect URL for post-payment callbacks
`is_split_link`	`true` if the payment is distributed to multiple recipients
`split_type`	`normal` (percentage-based) or `absolute` (fixed amounts)
`is_qr_link`	`true` if the link was created as a Personal QR link
`bank_transfer`	`true` if bank transfer payment is enabled for this link
`servicefee`	SecPaid service fee applied to this link
`recipients`	JSON array of recipient objects (split links only)
`transaction_type`	Derived: `Basic`, `Split`, or `Personal QR`
`pay_link`	The shareable payment URL
`qr_img`	URL of the generated QR code image

Payment Object (Pay-In)¶

Returned by getPayInTransactions.

{
    "pay_id": "string",
    "user_id": "string",
    "transaction_id": "string",
    "amount": "double",
    "net_amount": "double",
    "service_fee": "double",
    "service_fee_psp": "double",
    "status": "string",
    "recipient_note": "string",
    "payout_status": "string",
    "created_at": "datetime",
    "is_split_link": "false | true",
    "is_dispute": "false | true",
    "is_refund": "false | true",
    "payment_method": "string",
    "transaction_type": "string"
}

Field	Description
`pay_id`	Payment identifier — matches the link ID
`transaction_id`	Unique SecPaid transaction ID (format: `YYYYMMDD-pi-XXXXXXXXXX`)
`amount`	Gross amount paid by the customer
`net_amount`	Amount after all fees
`service_fee`	SecPaid service fee
`service_fee_psp`	Payment service provider (Stripe) fee
`status`	Payment status (e.g. `Success`, `Pending`)
`payout_status`	Whether this payment has been included in a payout (`Pending`, `Completed`)
`is_dispute`	Whether a dispute has been raised
`is_refund`	Whether a refund has been processed
`payment_method`	How the customer paid (e.g. `card`, `Bank Transfer`)
`transaction_type`	Derived: `Basic`, `Split`, `Personal QR`, `Refund`, `Dispute`, `Dispute Refund`

Payout Object¶

Returned by getPayOutTransactions.

{
    "payout_id": "string",
    "user_id": "string",
    "transaction_id": "string",
    "payout_amount": "double",
    "service_fee": "double",
    "net_amount": "double",
    "payout_status": "string",
    "request_date": "date",
    "created_at": "datetime",
    "is_split_link": "false | true",
    "is_dispute": "false | true",
    "is_refund": "false | true"
}

Field	Description
`payout_id`	Unique payout identifier
`transaction_id`	Unique payout transaction ID
`payout_amount`	Total gross amount being paid out
`service_fee`	SecPaid fee deducted from this payout
`net_amount`	Amount transferred to your account
`payout_status`	Current status (`Pending`, `InProgress`, `Completed`)
`request_date`	Date the payout was generated
`is_dispute`	Whether this payout relates to a dispute
`is_refund`	Whether this payout relates to a refund

Payouts are generated nightly, batching all successful pay-ins from the previous day.

Tax Invoice Object¶

Returned by getTaxInvoiceList.

{
    "invoice_id": "string",
    "user_id": "string",
    "invoice_date": "date",
    "service_month": "string"
}

Recipient Object (Split Links)¶

Used in the body of createSplitLink.

{
    "token": "string",
    "share": 50.00
}

Field	Description
`token`	The recipient's SecPaid recipient token
`share`	Their share as a percentage (0–100) for `normal` split type, or fixed EUR amount for `absolute` split type

Error Response¶

{
    "error": "string",
    "errorMessage": "string"
}

All error responses follow this structure. Refer to ResponseCode (0 = error, 1 = success) and ResponseMsg for programmatic handling.