Request refunds and read stored refund outcomes
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/orsunpay-com:orsunpay-com-refunds-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
name: OrsunPay
description: Server-to-server merchant payments. Money is always a decimal string in major units.
title: OrsunPay Merchant Refunds API
version: '1.0'
servers: []
tags:
- description: Request refunds and read stored refund outcomes
name: Refunds
paths:
/v1/payment/{id}/refunds:
get:
description: Read stored refunds for the authenticated merchant and API-key mode. Ordered by refund ID ascending, with at most 100 records per page. Pass nextCursor to continue; null means the final page.
operationId: listPaymentRefunds
parameters:
- description: Payment transaction ID
in: path
name: id
required: true
schema:
maxLength: 32
pattern: ^[A-Za-z0-9_-]{1,32}$
type: string
- in: query
name: limit
required: false
schema:
default: 100
maximum: 100
minimum: 1
type: number
- description: nextCursor from the preceding page; results are ordered by refund ID ascending.
in: query
name: cursor
required: false
schema:
maxLength: 32
pattern: ^[A-Za-z0-9_-]{1,32}$
type: string
responses:
'200':
content:
application/json:
example:
data:
- amount: '10.00'
createdAt: '2026-10-11T12:00:00.000Z'
currency: EUR
errorCode: null
id: rf_example
metadata:
orderReference: order_example
providerRefundId: null
reason: requested_by_customer
status: PENDING
transactionId: tr_example
updatedAt: '2026-10-11T12:00:00.000Z'
nextCursor: null
schema:
$ref: '#/components/schemas/RefundsResponseDto'
description: Stored refunds ordered by ID ascending
'400':
content:
application/json:
example:
error: Bad Request
message:
- Invalid refund input
statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/ValidationErrorResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: Invalid request, metadata or Idempotency-Key
'401':
content:
application/json:
example:
error: Unauthorized
message: Invalid API key
statusCode: 401
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponseDto'
description: Missing, invalid, expired or inactive merchant API key
'404':
content:
application/json:
example:
error: REFUND_NOT_FOUND
errorCode: REFUND_NOT_FOUND
message: REFUND_NOT_FOUND
status: false
statusCode: 404
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'REFUND_NOT_FOUND: unknown payment/refund or one belonging to another merchant or API-key mode'
'429':
content:
application/json:
example:
error: RATE_LIMITED
errorCode: RATE_LIMITED
message: Too many requests. Retry after the indicated delay.
status: false
statusCode: 429
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key.'
headers:
RateLimit:
description: Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory.
schema:
example: '"merchant";r=37;t=4'
type: string
RateLimit-Policy:
description: Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds.
schema:
example: '"merchant";q=100;w=5'
type: string
Retry-After:
description: Minimum delay in whole seconds before retrying.
schema:
example: 1
minimum: 1
type: integer
'503':
content:
application/json:
examples:
authentication:
value:
error: Service Unavailable
message: API_KEY_VALIDATION_UNAVAILABLE
statusCode: 503
refund:
value:
error: REFUND_SERVICE_UNAVAILABLE
errorCode: REFUND_SERVICE_UNAVAILABLE
message: REFUND_SERVICE_UNAVAILABLE
status: false
statusCode: 503
schema:
anyOf:
- $ref: '#/components/schemas/AuthenticationUnavailableResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: API-key validation or refund core is unavailable. A create may have committed; retry with the same Idempotency-Key.
security:
- X-API-Key: []
summary: List refunds for a payment
tags:
- Refunds
post:
description: Accepts an asynchronous refund in the authenticated merchant and API-key mode. Omit amount to refund the remaining refundable amount. PENDING/PROCESSING are not completion. The original connection must support refunds and payment and processing currencies must match. Idempotency-Key is mandatory.
operationId: createRefund
parameters:
- description: Payment transaction ID
in: path
name: id
required: true
schema:
maxLength: 32
pattern: ^[A-Za-z0-9_-]{1,32}$
type: string
- description: 'A single 1–255 character printable ASCII value without spaces. The checkout-submit: prefix is reserved (case-insensitive). Reuse the same key and body after an uncertain response.'
in: header
name: Idempotency-Key
required: true
schema:
example: refund-order-example-1
maxLength: 255
minLength: 1
pattern: ^[\x21-\x7e]+$
type: string
requestBody:
content:
application/json:
examples:
partial:
summary: Partial refund
value:
amount: '10.00'
metadata:
orderReference: order_example
reason: requested_by_customer
remaining:
summary: Refund the remaining amount
value: {}
schema:
$ref: '#/components/schemas/CreateRefundDto'
required: true
responses:
'201':
content:
application/json:
example:
data:
amount: '10.00'
createdAt: '2026-10-11T12:00:00.000Z'
currency: EUR
errorCode: null
id: rf_example
metadata:
orderReference: order_example
providerRefundId: null
reason: requested_by_customer
status: PENDING
transactionId: tr_example
updatedAt: '2026-10-11T12:00:00.000Z'
schema:
$ref: '#/components/schemas/RefundResponseDto'
description: Refund accepted for asynchronous execution
headers:
Idempotency-Replayed:
description: Returned when the response is an idempotent replay
schema:
enum:
- 'true'
type: string
'400':
content:
application/json:
example:
error: Bad Request
message:
- Invalid refund input
statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/ValidationErrorResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: Invalid request, metadata or Idempotency-Key
'401':
content:
application/json:
example:
error: Unauthorized
message: Invalid API key
statusCode: 401
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponseDto'
description: Missing, invalid, expired or inactive merchant API key
'404':
content:
application/json:
example:
error: REFUND_NOT_FOUND
errorCode: REFUND_NOT_FOUND
message: REFUND_NOT_FOUND
status: false
statusCode: 404
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'REFUND_NOT_FOUND: unknown payment/refund or one belonging to another merchant or API-key mode'
'409':
content:
application/json:
example:
error: REFUND_EXCEEDS_AMOUNT
errorCode: REFUND_EXCEEDS_AMOUNT
message: REFUND_EXCEEDS_AMOUNT
status: false
statusCode: 409
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE or IDEMPOTENCY_IN_PROGRESS. Currency conversion refunds are unsupported; payment and processing currencies must match.
headers:
Retry-After:
description: Seconds before retrying the same in-progress request
schema:
type: string
'422':
content:
application/json:
example:
error: REFUND_NOT_SUPPORTED
errorCode: REFUND_NOT_SUPPORTED
message: REFUND_NOT_SUPPORTED
status: false
statusCode: 422
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'REFUND_NOT_SUPPORTED (supported providers: Stripe, Mollie, Revolut and Viva), or IDEMPOTENCY_KEY_REUSED with different request input.'
'429':
content:
application/json:
example:
error: RATE_LIMITED
errorCode: RATE_LIMITED
message: Too many requests. Retry after the indicated delay.
status: false
statusCode: 429
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key.'
headers:
RateLimit:
description: Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory.
schema:
example: '"merchant";r=37;t=4'
type: string
RateLimit-Policy:
description: Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds.
schema:
example: '"merchant";q=100;w=5'
type: string
Retry-After:
description: Minimum delay in whole seconds before retrying.
schema:
example: 1
minimum: 1
type: integer
'503':
content:
application/json:
examples:
authentication:
value:
error: Service Unavailable
message: API_KEY_VALIDATION_UNAVAILABLE
statusCode: 503
refund:
value:
error: REFUND_SERVICE_UNAVAILABLE
errorCode: REFUND_SERVICE_UNAVAILABLE
message: REFUND_SERVICE_UNAVAILABLE
status: false
statusCode: 503
schema:
anyOf:
- $ref: '#/components/schemas/AuthenticationUnavailableResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: API-key validation or refund core is unavailable. A create may have committed; retry with the same Idempotency-Key.
security:
- X-API-Key: []
summary: Request a full or partial refund
tags:
- Refunds
/v1/refunds/{id}:
get:
description: Read the stored refund status in the authenticated merchant and API-key mode. Unknown and foreign refund IDs return the same 404.
operationId: getRefund
parameters:
- description: Refund ID
in: path
name: id
required: true
schema:
maxLength: 32
pattern: ^[A-Za-z0-9_-]{1,32}$
type: string
responses:
'200':
content:
application/json:
example:
data:
amount: '10.00'
createdAt: '2026-10-11T12:00:00.000Z'
currency: EUR
errorCode: null
id: rf_example
metadata:
orderReference: order_example
providerRefundId: null
reason: requested_by_customer
status: PENDING
transactionId: tr_example
updatedAt: '2026-10-11T12:00:00.000Z'
schema:
$ref: '#/components/schemas/RefundResponseDto'
description: Stored refund
'400':
content:
application/json:
example:
error: Bad Request
message:
- Invalid refund input
statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/ValidationErrorResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: Invalid request, metadata or Idempotency-Key
'401':
content:
application/json:
example:
error: Unauthorized
message: Invalid API key
statusCode: 401
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponseDto'
description: Missing, invalid, expired or inactive merchant API key
'404':
content:
application/json:
example:
error: REFUND_NOT_FOUND
errorCode: REFUND_NOT_FOUND
message: REFUND_NOT_FOUND
status: false
statusCode: 404
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'REFUND_NOT_FOUND: unknown payment/refund or one belonging to another merchant or API-key mode'
'429':
content:
application/json:
example:
error: RATE_LIMITED
errorCode: RATE_LIMITED
message: Too many requests. Retry after the indicated delay.
status: false
statusCode: 429
schema:
$ref: '#/components/schemas/ApiErrorResponseDto'
description: 'RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key.'
headers:
RateLimit:
description: Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory.
schema:
example: '"merchant";r=37;t=4'
type: string
RateLimit-Policy:
description: Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds.
schema:
example: '"merchant";q=100;w=5'
type: string
Retry-After:
description: Minimum delay in whole seconds before retrying.
schema:
example: 1
minimum: 1
type: integer
'503':
content:
application/json:
examples:
authentication:
value:
error: Service Unavailable
message: API_KEY_VALIDATION_UNAVAILABLE
statusCode: 503
refund:
value:
error: REFUND_SERVICE_UNAVAILABLE
errorCode: REFUND_SERVICE_UNAVAILABLE
message: REFUND_SERVICE_UNAVAILABLE
status: false
statusCode: 503
schema:
anyOf:
- $ref: '#/components/schemas/AuthenticationUnavailableResponseDto'
- $ref: '#/components/schemas/ApiErrorResponseDto'
description: API-key validation or refund core is unavailable. A create may have committed; retry with the same Idempotency-Key.
security:
- X-API-Key: []
summary: Get a refund
tags:
- Refunds
components:
schemas:
AuthenticationUnavailableResponseDto:
properties:
error:
example: Service Unavailable
type: string
message:
example: API_KEY_VALIDATION_UNAVAILABLE
type: string
statusCode:
example: 503
type: number
required:
- statusCode
- error
- message
type: object
UnauthorizedErrorResponseDto:
properties:
error:
example: Unauthorized
type: string
errorCode:
description: Stable authentication error code when available
example: API_KEY_ROTATION_REQUIRED
type: string
message:
example: Invalid API key
type: string
statusCode:
description: HTTP status when included by the error handler
example: 401
type: number
required:
- message
type: object
CreateRefundDto:
properties:
amount:
description: Positive decimal string in the payment currency, within its currency precision. Omit to refund the remaining refundable amount.
example: '10.00'
maxLength: 80
pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
type: string
metadata:
additionalProperties: true
description: JSON object, at most 16384 UTF-8 bytes when serialized; maximum container depth 10 (root depth 0). Do not include sensitive customer or payment data.
type: object
reason:
default: requested_by_customer
enum:
- requested_by_customer
- duplicate
- fraudulent
- other
type: string
type: object
ApiErrorResponseDto:
properties:
error:
description: Same as errorCode
example: DUPLICATE_ORDER_ID
type: string
errorCode:
description: 'Machine-readable, extensible code. Known values: ADYEN_REFUSED, CARD_DATA_NOT_ACCEPTED, RATE_LIMITED, PAYMENT_LINK_INVALID_AMOUNT, PAYMENT_LINK_UNSUPPORTED_CURRENCY, PAYMENT_LINK_INVALID_EXPIRY, PAYMENT_LINK_INVALID_MAX_USES, PAYMENT_LINK_REDIRECT_URL_NOT_ALLOWED, PAYMENT_LINK_METADATA_TOO_LARGE, PAYMENT_LINK_INVALID_TEXT, PAYMENT_LINK_NOT_FOUND, PAYMENT_LINK_INVALID_LIMIT, PAYMENT_LINK_INVALID_CURSOR, API_KEY_ROTATION_REQUIRED, ORDER_ID_RESERVED, NO_CREDENTIALS_FOR_MODE, LIVEMODE_MISMATCH, PSP_OUTCOME_UNKNOWN, PAYMENT_METHOD_REQUIRED, PAYMENT_METHOD_INPUT_WITHOUT_METHOD, NO_PAYMENT_METHODS, IDEMPOTENCY_KEY_INVALID, DUPLICATE_ORDER_ID, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, REFUND_INVALID_AMOUNT, REFUND_INVALID_REASON, REFUND_INVALID_METADATA, REFUND_INPUT_INVALID, REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE, REFUND_NOT_FOUND, REFUND_NOT_SUPPORTED, IDEMPOTENCY_LEASE_LOST, REFUND_SERVICE_UNAVAILABLE. New codes may be added; clients must handle unknown values.'
example: DUPLICATE_ORDER_ID
type: string
existingTransactionId:
description: 'DUPLICATE_ORDER_ID only: the transaction that already uses this orderId'
example: tr_x8k2p0q5scocndpejk0nud75q
type: string
fields:
description: Invalid or missing buyer contact fields for CUSTOMER_CONTACT_REQUIRED
example:
- customer.email
- customer.country
items:
type: string
type: array
idempotencyKey:
description: IDEMPOTENCY_* errors only
example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10
type: string
message:
example: A transaction with orderId "A-1001" already exists for this merchant
type: string
orderId:
description: DUPLICATE_ORDER_ID only
example: A-1001
type: string
status:
example: false
type: boolean
statusCode:
example: 409
type: number
required:
- status
- statusCode
- errorCode
- error
- message
type: object
ValidationErrorResponseDto:
properties:
error:
example: Bad Request
type: string
message:
example:
- amount must be a decimal string in major units, e.g. "12.30"; JSON numbers are not accepted for money (got 12.3)
items:
type: string
type: array
statusCode:
example: 400
type: number
required:
- statusCode
- error
- message
type: object
RefundResponseDto:
properties:
data:
$ref: '#/components/schemas/RefundDto'
required:
- data
type: object
RefundDto:
properties:
amount:
example: '10.00'
pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
type: string
createdAt:
format: date-time
type: string
currency:
example: EUR
type: string
errorCode:
anyOf:
- type: string
- type: 'null'
id:
example: rf_example
type: string
metadata:
additionalProperties: true
type: object
providerRefundId:
anyOf:
- type: string
- type: 'null'
reason:
enum:
- requested_by_customer
- duplicate
- fraudulent
- other
type: string
status:
enum:
- PENDING
- PROCESSING
- SUCCEEDED
- FAILED
- CANCELED
type: string
transactionId:
example: tr_example
type: string
updatedAt:
format: date-time
type: string
required:
- id
- transactionId
- amount
- currency
- status
- reason
- providerRefundId
- errorCode
- metadata
- createdAt
- updatedAt
type: object
RefundsResponseDto:
properties:
data:
items:
$ref: '#/components/schemas/RefundDto'
type: array
nextCursor:
anyOf:
- type: string
- type: 'null'
required:
- data
- nextCursor
type: object
securitySchemes:
X-API-Key:
in: header
name: x-api-key
type: apiKey
bearer:
bearerFormat: Opaque cashier player grant
scheme: bearer
type: http