Adyen Stored Value API
A set of API endpoints to manage stored value products.
OpenAPI Specification
openapi: 3.1.0
servers:
- url: https://pal-test.adyen.com/pal/servlet/StoredValue/v46
info:
version: '46'
x-publicVersion: true
title: Adyen Stored Value API
description: A set of API endpoints to manage stored value products.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
x-groups:
- General
tags:
- name: changeStatus
- name: checkBalance
- name: Issue
- name: Load
- name: mergeBalance
- name: voidTransaction
paths:
/changeStatus:
post:
tags:
- changeStatus
summary: Adyen Changes the Status of the Payment Method.
description: >-
Changes the status of the provided payment method to the specified
status.
operationId: post-changeStatus
x-groupName: General
x-sortIndex: 0
x-methodName: changeStatus
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueStatusChangeRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueStatusChangeResponse'
examples:
post-changeStatus200Example:
summary: Default post-changeStatus 200 response
x-microcks-default: true
value:
authCode: CODE123
currentBalance: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-changeStatus400Example:
summary: Default post-changeStatus 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-changeStatus401Example:
summary: Default post-changeStatus 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-changeStatus403Example:
summary: Default post-changeStatus 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-changeStatus500Example:
summary: Default post-changeStatus 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/checkBalance:
post:
tags:
- checkBalance
summary: Adyen Checks the Balance.
description: Checks the balance of the provided payment method.
operationId: post-checkBalance
x-groupName: General
x-sortIndex: 0
x-methodName: checkBalance
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueBalanceCheckRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueBalanceCheckResponse'
examples:
post-checkBalance200Example:
summary: Default post-checkBalance 200 response
x-microcks-default: true
value:
currentBalance: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-checkBalance400Example:
summary: Default post-checkBalance 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-checkBalance401Example:
summary: Default post-checkBalance 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-checkBalance403Example:
summary: Default post-checkBalance 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-checkBalance500Example:
summary: Default post-checkBalance 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/issue:
post:
tags:
- Issue
summary: Adyen Issues a New Card.
description: Issues a new card of the given payment method.
operationId: post-issue
x-groupName: General
x-sortIndex: 0
x-methodName: issue
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueIssueRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueIssueResponse'
examples:
post-issue200Example:
summary: Default post-issue 200 response
x-microcks-default: true
value:
authCode: CODE123
currentBalance: example_value
paymentMethod: {}
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-issue400Example:
summary: Default post-issue 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-issue401Example:
summary: Default post-issue 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-issue403Example:
summary: Default post-issue 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-issue500Example:
summary: Default post-issue 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/load:
post:
tags:
- Load
summary: Adyen Loads the Payment Method.
description: Loads the payment method with the specified funds.
operationId: post-load
x-groupName: General
x-sortIndex: 0
x-methodName: load
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueLoadRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueLoadResponse'
examples:
post-load200Example:
summary: Default post-load 200 response
x-microcks-default: true
value:
authCode: CODE123
currentBalance: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-load400Example:
summary: Default post-load 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-load401Example:
summary: Default post-load 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-load403Example:
summary: Default post-load 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-load500Example:
summary: Default post-load 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/mergeBalance:
post:
tags:
- mergeBalance
summary: Adyen Merge the Balance of Two Cards.
description: >-
Increases the balance of the paymentmethod by the full amount left on
the source paymentmethod
operationId: post-mergeBalance
x-groupName: General
x-sortIndex: 0
x-methodName: mergeBalance
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueBalanceMergeRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueBalanceMergeResponse'
examples:
post-mergeBalance200Example:
summary: Default post-mergeBalance 200 response
x-microcks-default: true
value:
authCode: CODE123
currentBalance: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-mergeBalance400Example:
summary: Default post-mergeBalance 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-mergeBalance401Example:
summary: Default post-mergeBalance 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-mergeBalance403Example:
summary: Default post-mergeBalance 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-mergeBalance500Example:
summary: Default post-mergeBalance 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/voidTransaction:
post:
tags:
- voidTransaction
summary: Adyen Voids a Transaction.
description: Voids the referenced stored value transaction.
operationId: post-voidTransaction
x-groupName: General
x-sortIndex: 0
x-methodName: voidTransaction
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueVoidRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StoredValueVoidResponse'
examples:
post-voidTransaction200Example:
summary: Default post-voidTransaction 200 response
x-microcks-default: true
value:
currentBalance: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: Success
thirdPartyRefusalReason: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-voidTransaction400Example:
summary: Default post-voidTransaction 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-voidTransaction401Example:
summary: Default post-voidTransaction 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-voidTransaction403Example:
summary: Default post-voidTransaction 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-voidTransaction500Example:
summary: Default post-voidTransaction 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Amount:
properties:
currency:
description: >-
The three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: >-
The amount of the transaction, in [minor
units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
ServiceError:
properties:
additionalData:
x-addedInVersion: '46'
additionalProperties:
type: string
description: >-
Contains additional information about the payment. Some data fields
are included only if you select them first. Go to **Customer Area**
> **Developers** > **Additional data**.
type: object
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
type: object
StoredValueBalanceCheckRequest:
properties:
amount:
description: The amount information for the transaction.
$ref: '#/components/schemas/Amount'
merchantAccount:
description: >-
The merchant account identifier, with which you want to process the
transaction.
type: string
paymentMethod:
additionalProperties:
type: string
description: >-
The collection that contains the type of the payment method and its
specific information if available
type: object
recurringDetailReference:
type: string
reference:
description: >-
The reference to uniquely identify a payment. This reference is used
in all communication with you about the payment status. We recommend
using a unique value per payment; however, it is not a requirement.
If you need to provide multiple references for a transaction,
separate them with hyphens ("-").
Maximum length: 80 characters.
type: string
shopperInteraction:
description: >-
Specifies the sales channel, through which the shopper gives their
card details, and whether the shopper is a returning customer.
For the web service API, Adyen assumes Ecommerce shopper interaction
by default.
This field has the following possible values:
* `Ecommerce` - Online transactions where the cardholder is present
(online). For better authorisation rates, we recommend sending the
card security code (CSC) along with the request.
* `ContAuth` - Card on file and/or subscription transactions, where
the cardholder is known to the merchant (returning customer). If the
shopper is present (online), you can supply also the CSC to improve
authorisation (one-click payment).
* `Moto` - Mail-order and telephone-order transactions where the
shopper is in contact with the merchant via email or telephone.
* `POS` - Point-of-sale transactions where the shopper is physically
present to make a payment using a secure payment terminal.
enum:
- Ecommerce
- ContAuth
- Moto
- POS
type: string
shopperReference:
type: string
store:
description: The physical store, for which this payment is processed.
maxLength: 16
minLength: 1
type: string
required:
- merchantAccount
- reference
- paymentMethod
type: object
StoredValueBalanceCheckResponse:
properties:
currentBalance:
description: The balance currently on the payment method.
$ref: '#/components/schemas/Amount'
pspReference:
description: >-
Adyen's 16-character string reference associated with the
transaction/request. This value is globally unique; quote it when
communicating with us about this request.
type: string
refusalReason:
description: >-
If the transaction is refused or an error occurs, this field holds
Adyen's mapped reason for the refusal or a description of the error.
When a transaction fails, the authorisation response includes
`resultCode` and `refusalReason` values.
type: string
resultCode:
description: >
The result of the payment. Possible values:
* **Success** – The operation has been completed successfully.
* **Refused** – The operation was refused. The reason is given in
the `refusalReason` field.
* **Error** – There was an error when the operation was processed.
The reason is given in the `refusalReason` field.
* **NotEnoughBalance** – The amount on the payment method is lower
than the amount given in the request. Only applicable to balance
checks.
enum:
- Success
- Refused
- Error
- NotEnoughBalance
type: string
thirdPartyRefusalReason:
description: Raw refusal reason received from the third party, where available
type: string
type: object
StoredValueBalanceMergeRequest:
properties:
amount:
description: The amount information for the transaction.
$ref: '#/components/schemas/Amount'
merchantAccount:
description: >-
The merchant account identifier, with which you want to process the
transaction.
type: string
paymentMethod:
additionalProperties:
type: string
description: >-
The collection that contains the type of the payment method and its
specific information if available
type: object
recurringDetailReference:
type: string
reference:
description: >-
The reference to uniquely identify a payment. This reference is used
in all communication with you about the payment status. We recommend
using a unique value per payment; however, it is not a requirement.
If you need to provide multiple references for a transaction,
separate them with hyphens ("-").
Maximum length: 80 characters.
type: string
shopperInteraction:
description: >-
Specifies the sales channel, through which the shopper gives their
card details, and whether the shopper is a returning customer.
For the web service API, Adyen assumes Ecommerce shopper interaction
by default.
This field has the following possible values:
* `Ecommerce` - Online transactions where the cardholder is present
(online). For better authorisation rates, we recommend sending the
card security code (CSC) along with the request.
* `ContAuth` - Card on file and/or subscription transactions, where
the cardholder is known to the merchant (returning customer). If the
shopper is present (online), you can supply also the CSC to improve
authorisation (one-click payment).
* `Moto` - Mail-order and telephone-order transactions where the
shopper is in contact with the merchant via email or telephone.
* `POS` - Point-of-sale transactions where the shopper is physically
present to make a payment using a secure payment terminal.
enum:
- Ecommerce
- ContAuth
- Moto
- POS
type: string
shopperReference:
type: string
sourcePaymentMethod:
additionalProperties:
type: string
description: >-
The collection that contains the source payment method and
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/stored-value-openapi-original.yml