Start a payment-link session

Possession of the payment link ID addresses this checkout. The fixed amount comes from the dashboard link, never the request body.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

POSThttps://api.veyqo.org/checkout/v1/links/{id}/sessionsIntegration guide

Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.

Start a payment-link session

curl --request POST "https://api.veyqo.org/checkout/v1/links/$PAYMENT_LINK_ID/sessions" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "email": "customer@example.com"
}'

{
  "success": true,
  "data": {
    "id": "cs_01M6EB66SC61Q3RQYAN0693DGM",
    "object": "checkout_session",
    "url": "https://veyqo.org/pay/cs_01M6EB66SC61Q3RQYAN0693DGM",
    "status": "open",
    "source": "link",
    "provider": "paystack",
    "amount": 50000,
    "currency": "NGN",
    "reference": "ORDER-1001",
    "description": "Order 1001",
    "customer_email": "customer@example.com",
    "payment": null,
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "expires_at": "2026-11-02T13:00:00+00:00",
    "completed_at": null,
    "created_at": "2026-11-02T12:00:00+00:00"
  }
}

Illustrative examples. Replace IDs and environment variables with your own values. Keep secret keys on your server.

Headers

Content-Typestringrequired: application/json
Acceptstringoptional: application/json

Endpoint

POST https://api.veyqo.org/checkout/v1/links/{id}/sessions

The resource ID addresses this customer checkout. Do not expose it unnecessarily. This endpoint supports the hosted page and checkout script.

Path and query parameters

Parameter	Location	Required	Description
id	path	Yes	Use the ID returned when this resource was created.

Request body

emailstring | nulloptional: Maximum 255 characters. Format: email.
namestring | nulloptional: Maximum 255 characters.

Response fields

idstringrequired: Checkout session ID (cs_ prefix).
object"checkout_session"required: See the JSON example.
urlstringrequired: Hosted Veyqo URL; redirect here or open this session using VeyqoCheckout. Format: uri.
statusstringrequired: Values: open, completed, expired.
sourcestringrequired: Values: api, browser, link.
providerstringrequired: Selected provider slug; this field is an object on the browser session detail endpoint.
amountintegerrequired: Server-defined amount in minor units.
currencystringrequired: Three-letter currency.
referencestring | nullrequired: Your order reference, when supplied.
descriptionstring | nullrequired: Checkout description.
customer_emailstring | nullrequired: Customer email if already supplied.
paymentobject | nullrequired: Current payment attempt, if any. A session can have multiple attempts over time.
success_urlstring | nullrequired: Configured return URL. A redirect is not proof of payment.
cancel_urlstring | nullrequired: Configured cancellation URL.
expires_atstringrequired: Session expiry time. Format: date-time.
completed_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.
created_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.

Errors and recovery

Code	HTTP	Recovery	Retry policy
VALIDATION_FAILED	422	Read error.details when present, correct the named fields and retry only after correction. Validation messages may describe state/capability errors without field details.	No automatic retry.
RESOURCE_NOT_FOUND	404	Check the ID, project and environment. Do not guess another project’s IDs. An inactive payment link is also not-found.	No blind retry.
RATE_LIMIT_EXCEEDED	429	Honor Retry-After, use bounded exponential backoff with jitter, and reduce concurrent requests. Read X-RateLimit headers.	Yes, after Retry-After; preserve write idempotency.
PROVIDER_UNAVAILABLE	503	Check the existing payment and verify its state before starting another attempt. Retry safe reads with backoff; preserve operation identity for retried writes.	Conditional: reconcile unknown outcomes first.
INTERNAL_ERROR	500	Record X-Request-Id, timestamp and sanitized request context. Reconcile unknown payment outcomes before retrying a write; contact support if it persists.	Safe reads: bounded backoff. Writes: reconcile first.

Complete error catalogue

Every Veyqo error code, including which surface emits it and how to recover.