Start a checkout method

Possession of the session ID addresses this customer checkout. These endpoints support the hosted page and SDK; prefer those clients over reimplementing provider-specific actions.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

POSThttps://api.veyqo.org/checkout/v1/sessions/{id}/chargeIntegration guide

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

Start a checkout method

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

{
  "success": true,
  "data": {
    "id": "cs_01M6EB66SC61Q3RQYAN0693DGM",
    "object": "checkout_session",
    "url": "https://veyqo.org/pay/cs_01M6EB66SC61Q3RQYAN0693DGM",
    "status": "open",
    "source": "api",
    "provider": {
      "slug": "paystack",
      "name": "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",
    "merchant": {
      "name": "Example Store"
    },
    "sandbox": true,
    "needs_email": false,
    "methods": [
      {
        "id": "card"
      },
      {
        "id": "bank_transfer"
      },
      {
        "id": "ussd",
        "banks": [
          {
            "code": "737",
            "name": "GTBank"
          },
          {
            "code": "919",
            "name": "UBA"
          },
          {
            "code": "822",
            "name": "Sterling Bank"
          },
          {
            "code": "966",
            "name": "Zenith Bank"
          }
        ]
      }
    ],
    "next_action": null
  }
}

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/sessions/{id}/charge

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

methodstringrequired: Values: card, bank_transfer, ussd, mobile_money.
emailstring | nulloptional: Maximum 255 characters. Format: email.
namestring | nulloptional: Maximum 255 characters.
phonestring | nulloptional: Maximum 32 characters.
bankstring | nulloptional: Bank code returned in the available method options. Maximum 10 characters.
networkstring | nulloptional: Mobile-money network code from the method options. Maximum 10 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.
providerobject | nullrequired: Available provider identity, never secret credentials.
provider.slugstringoptional: See the JSON example.
provider.namestringoptional: See the JSON example.
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.
merchantobjectrequired: See the JSON example.
merchant.namestringrequired: See the JSON example.
sandboxbooleanrequired: See the JSON example.
needs_emailbooleanrequired: See the JSON example.
methodsarrayrequired: Currency-dependent method descriptions. Use the hosted page/SDK instead of hard-coding this provider-specific payload.
next_actionobject | nullrequired: Provider-specific action for the hosted checkout: bank details, USSD instructions, OTP or secure card form. May change per method.

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.