openapi: 3.0.3
info:
  title: Yoco Online Payments Checkout Payment Links API
  version: '2026-07-12'
  description: 'Hand-authored OpenAPI for Yoco''s online payments platform, grounded in the public Yoco developer hub (developer.yoco.com). Two surfaces are covered: the Checkout API on https://payments.yoco.com/api (secret-key Bearer auth) for creating hosted checkouts, issuing refunds, and managing webhook endpoints; and the versioned Yoco API on https://api.yoco.com/v1 (JWT Bearer auth with scopes) for reading payments, refunds, and payment links. Operations marked `x-status: modeled` were inferred from the resource design and referenced-but-not-fully-rendered doc pages and should be reconciled against the live docs. All others were confirmed against live reference pages. This document was not fetched from an upstream Yoco OpenAPI file.'
  contact:
    name: Yoco Developers
    url: https://developer.yoco.com
  x-provider: Yoco
  x-authored-by: API Evangelist
servers:
- url: https://payments.yoco.com/api
  description: Checkout API (secret-key Bearer auth)
tags:
- name: Payment Links
  description: Read shareable payment links (versioned Yoco API).
paths:
  /v1/payment_links/{paymentLinkId}:
    get:
      operationId: getPaymentLink
      summary: Fetch a payment link
      description: Retrieve a payment link by identifier. Part of the versioned Yoco API on https://api.yoco.com. Requires the business/orders:read scope.
      tags:
      - Payment Links
      servers:
      - url: https://api.yoco.com
        description: Yoco API - production
      security:
      - jwtBearer: []
      parameters:
      - name: paymentLinkId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payment link found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '404':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        errorType:
          type: string
        errorCode:
          type: string
        description:
          type: string
    PaymentLink:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: 'Secret integration key passed as `Authorization: Bearer sk_live_...` (live) or `Authorization: Bearer sk_test_...` (test). Obtain keys in the Yoco app under Sales -> Payment Gateway. Use server-side only.'
    jwtBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer credential for the versioned Yoco API (api.yoco.com/v1), authorized with scopes such as business/orders:read.