openapi: 3.0.3
info:
  title: Yoco Online Payments Checkout Refunds 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: Refunds
  description: Refund completed checkouts and read refund records.
paths:
  /checkouts/{checkoutId}/refund:
    post:
      operationId: refundCheckout
      summary: Refund a checkout
      description: Refunds a completed checkout in full, or in part when an amount is supplied. The refund may complete synchronously or resolve asynchronously; a refund.succeeded webhook confirms the final state.
      tags:
      - Refunds
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/CheckoutId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
      responses:
        '200':
          description: Refund accepted or completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResult'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /v1/refunds/{refundId}:
    get:
      operationId: getRefund
      summary: Fetch a refund
      description: Retrieve a refund record by identifier. Part of the versioned Yoco API on https://api.yoco.com. Requires the business/orders:read scope.
      tags:
      - Refunds
      servers:
      - url: https://api.yoco.com
        description: Yoco API - production
      security:
      - jwtBearer: []
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Refund found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '404':
          $ref: '#/components/responses/Error'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Optional idempotency key to prevent duplicate creation.
      schema:
        type: string
    CheckoutId:
      name: checkoutId
      in: path
      required: true
      schema:
        type: string
  schemas:
    RefundResult:
      type: object
      properties:
        id:
          type: string
          description: The checkout identifier.
        refundId:
          type: string
        message:
          type: string
        status:
          type: string
          description: succeeded or pending.
    RefundRequest:
      type: object
      properties:
        amount:
          type: integer
          description: Amount to refund in cents. Omit for a full refund.
        metadata:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        errorType:
          type: string
        errorCode:
          type: string
        description:
          type: string
    Refund:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: e.g. refund.succeeded.
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string
        metadata:
          type: object
          additionalProperties: true
  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.