Versioned read API for querying payment records. GET /v1/payments supports cursor pagination and filters by status and created/updated timestamps. Requests use JWT Bearer credentials scoped with business/orders:read. A sandbox host (api.yocosandbox.com) is available for testing.
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