Yoco Webhooks API

openapi: 3.0.3
info:
  title: Yoco Online Payments 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: Checkout
  description: Create and manage hosted checkout sessions.
- name: Refunds
  description: Refund completed checkouts and read refund records.
- name: Webhooks
  description: Register and manage webhook endpoints for event notifications.
- name: Payments
  description: Read payment records (versioned Yoco API).
- name: Payment Links
  description: Read shareable payment links (versioned Yoco API).
paths:
  /checkouts:
    post:
      operationId: createCheckout
      summary: Create a checkout
      description: >-
        Creates a hosted checkout session and returns a redirectUrl to send the
        customer to. Call this server-side to protect your secret key. Confirm
        the final outcome via the payment.succeeded webhook, not the successUrl.
      tags:
      - Checkout
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Checkout created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /checkouts/{checkoutId}:
    get:
      operationId: getCheckout
      summary: Get a checkout
      description: Retrieve a checkout session by its identifier.
      tags:
      - Checkout
      x-status: modeled
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/CheckoutId'
      responses:
        '200':
          description: Checkout found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
        '404':
          $ref: '#/components/responses/Error'
  /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'
  /webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      description: Lists the webhook endpoints registered for your account.
      tags:
      - Webhooks
      security:
      - secretKey: []
      responses:
        '200':
          description: A list of webhook subscriptions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    post:
      operationId: registerWebhook
      summary: Register a webhook
      description: Registers a webhook endpoint that Yoco will POST signed events to.
      tags:
      - Webhooks
      security:
      - secretKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: Webhook registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/Error'
  /webhooks/{webhookId}:
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: Removes a registered webhook endpoint.
      tags:
      - Webhooks
      x-status: modeled
      security:
      - secretKey: []
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Webhook deleted.
        '404':
          $ref: '#/components/responses/Error'
  /v1/payments:
    get:
      operationId: listPayments
      summary: List payments
      description: >-
        Lists payment records with cursor pagination. Filter by status and by
        created/updated timestamps. Part of the versioned Yoco API on
        https://api.yoco.com.
      tags:
      - Payments
      servers:
      - url: https://api.yoco.com
        description: Yoco API - production
      - url: https://api.yocosandbox.com
        description: Yoco API - sandbox
      security:
      - jwtBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum: [approved, cancelled, failed, pending]
      - name: created_at__gte
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at__lte
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_at__gte
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: updated_at__lte
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: A page of payment records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '401':
          $ref: '#/components/responses/Error'
  /v1/payments/{paymentId}:
    get:
      operationId: getPayment
      summary: Get a payment
      description: Retrieve a single payment record by identifier.
      tags:
      - Payments
      x-status: modeled
      servers:
      - url: https://api.yoco.com
        description: Yoco API - production
      security:
      - jwtBearer: []
      parameters:
      - name: paymentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payment found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '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'
  /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:
  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.
  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
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CheckoutRequest:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: integer
          description: Amount to charge, in the currency's minor unit (cents).
        currency:
          type: string
          description: Three-letter ISO 4217 currency code (e.g. ZAR).
        cancelUrl:
          type: string
          format: uri
        successUrl:
          type: string
          format: uri
        failureUrl:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
        totalTaxAmount:
          type: integer
          description: Display-only total tax, in cents.
        totalDiscount:
          type: integer
          description: Display-only total discount, in cents.
        lineItems:
          type: array
          description: Display-only line items.
          items:
            $ref: '#/components/schemas/LineItem'
    LineItem:
      type: object
      properties:
        displayName:
          type: string
        quantity:
          type: integer
        pricingDetails:
          type: object
          additionalProperties: true
    Checkout:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          description: e.g. created, started, processing, completed.
        amount:
          type: integer
        currency:
          type: string
        redirectUrl:
          type: string
          format: uri
        paymentId:
          type: string
        successUrl:
          type: string
          format: uri
        cancelUrl:
          type: string
          format: uri
        failureUrl:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
        merchantId:
          type: string
        totalDiscount:
          type: integer
        totalTaxAmount:
          type: integer
        subtotalAmount:
          type: integer
        processingMode:
          type: string
        externalId:
          type: string
    RefundRequest:
      type: object
      properties:
        amount:
          type: integer
          description: Amount to refund in cents. Omit for a full refund.
        metadata:
          type: object
          additionalProperties: true
    RefundResult:
      type: object
      properties:
        id:
          type: string
          description: The checkout identifier.
        refundId:
          type: string
        message:
          type: string
        status:
          type: string
          description: succeeded or pending.
    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
    WebhookRequest:
      type: object
      required:
      - name
      - url
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
    Webhook:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        mode:
          type: string
          description: test or live.
    PaymentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        cursor:
          type: string
          description: Cursor for the next page, if present.
    Payment:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [approved, cancelled, failed, pending]
        amount:
          type: integer
        currency:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
    PaymentLink:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string
    Error:
      type: object
      properties:
        errorType:
          type: string
        errorCode:
          type: string
        description:
          type: string