mirror of
https://github.com/gcatanese/adyen-openapi.git
synced 2026-03-10 08:01:24 +00:00
333 lines
13 KiB
YAML
333 lines
13 KiB
YAML
openapi: 3.1.0
|
|
servers:
|
|
- url: https://balanceplatform-api-test.adyen.com/fx/api/v1
|
|
description: Test Environment
|
|
- url: https://balanceplatform-api-live.adyen.com/fx/api/v1
|
|
description: Live Environment
|
|
info:
|
|
title: Foreign Exchange API
|
|
description: "The Foreign Exchange API allows you to manage and convert the currencies\
|
|
\ that are enabled for your integration.\n## Authentication\nWe recommend that\
|
|
\ you use an API key to connect to the Foreign Exchange API. You can generate\
|
|
\ an API key in your Customer Area. If you have an Adyen Issuing integration,\
|
|
\ generate an API key in your Balance Platform Customer Area.\n### Credential\
|
|
\ format\n* For the `rates/calculate` endpoint: Generate an API key for the credential\
|
|
\ with the format **ws@BalancePlatform.[YourBalancePlatform]**.\n\n### Header\
|
|
\ format\nTo connect to the Foreign Exchange API, add an `X-API-Key` header with\
|
|
\ the API key as the value, for example:\n\n ```\ncurl\n-H 'Content-Type: application/json'\
|
|
\ \\\n-H 'X-API-Key: ADYEN_API_KEY' \\\n...\n```\n\n## Versioning\n\nThe Foreign\
|
|
\ Exchange API supports [versioning](https://docs.adyen.com/development-resources/versioning)\
|
|
\ using a version suffix in the endpoint URL. This suffix has the following format:\
|
|
\ \"vXX\", where XX is the version number.\n\nFor example:\n\nhttps://balanceplatform-api-test.adyen.com/fx/v1/rates/calculate\n\
|
|
\n## Going live\nWhen going live, generate an API key in your [live Customer Area](https://ca-live.adyen.com/ca/).\
|
|
\ If you have an Adyen Issuing integration, [generate an API key](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service/#generate-api-key)\
|
|
\ in your [live Balance Platform Customer Area](https://balanceplatform-live.adyen.com/balanceplatform/).\
|
|
\ You can then use the API key to send requests to `https://balanceplatform-api-test.adyen.com/fx/v1`.\n\
|
|
\n"
|
|
termsOfService: https://www.adyen.com/legal/terms-and-conditions
|
|
contact:
|
|
name: Adyen Developer Experience team
|
|
url: https://github.com/Adyen/adyen-openapi
|
|
version: '1'
|
|
x-timestamp: '2025-02-11T15:32:15Z'
|
|
tags:
|
|
- name: Rates
|
|
paths:
|
|
/rates/calculate:
|
|
post:
|
|
tags:
|
|
- Rates
|
|
summary: Calculate amount in a different currency
|
|
description: Returns the calculated amounts and rates required to convert the
|
|
currency of a transaction.
|
|
operationId: post-rates-calculate
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CalculateRateRequest'
|
|
examples:
|
|
calculate:
|
|
summary: Calculate an amount in a different currency
|
|
description: The request to calculate an amount in a different currency.
|
|
value:
|
|
exchangeCalculations:
|
|
- type: splitPayment
|
|
sourceAmount:
|
|
currency: CZK
|
|
value: 112300
|
|
targetCurrency: EUR
|
|
exchangeSide: buy
|
|
- type: splitRefund
|
|
sourceAmount:
|
|
currency: CZK
|
|
value: 24000
|
|
targetCurrency: USD
|
|
exchangeSide: sell
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CalculateRateResponse'
|
|
examples:
|
|
calculate:
|
|
summary: Amount calculated in a different currency
|
|
description: The response returned when you calculate an amount
|
|
in a different currency.
|
|
value:
|
|
exchangeCalculations:
|
|
- type: splitPayment
|
|
exchangeSide: buy
|
|
sourceAmount:
|
|
value: 112300
|
|
currency: CZK
|
|
targetAmount:
|
|
value: 4480
|
|
currency: EUR
|
|
appliedExchangeRate: 0.039893143366
|
|
- type: splitRefund
|
|
exchangeSide: sell
|
|
sourceAmount:
|
|
value: 24000
|
|
currency: CZK
|
|
targetAmount:
|
|
value: 992
|
|
currency: USD
|
|
appliedExchangeRate: 0.0413333333333
|
|
'401':
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DefaultErrorResponseEntity'
|
|
examples:
|
|
calculate-401:
|
|
summary: Unauthorized
|
|
description: Authentication failed.
|
|
value:
|
|
type: https://docs.adyen.com/errors/unauthorized
|
|
title: Unauthorized
|
|
status: 401
|
|
errorCode: '00_401'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DefaultErrorResponseEntity'
|
|
examples:
|
|
calculate-403:
|
|
summary: Forbidden
|
|
description: Most commonly happens when user does not have sufficient
|
|
roles or doesn't own requested resource.
|
|
value:
|
|
type: https://docs.adyen.com/errors/forbidden
|
|
errorCode: '00_403'
|
|
title: Forbidden
|
|
detail: User doesn't have access to all token policy resources
|
|
requestId: d42c493b5176df89e51516c6060cc34c
|
|
status: 403
|
|
'422':
|
|
description: Unprocessable Entity - a request validation error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DefaultErrorResponseEntity'
|
|
examples:
|
|
calculate-422:
|
|
summary: Bad request
|
|
description: Response returned when request parsing has failed or
|
|
some request fields were invalid.
|
|
value:
|
|
type: https://docs.adyen.com/errors/unprocessable-entity
|
|
errorCode: '999_422_000'
|
|
title: Validation failure
|
|
detail: Input data validation failed
|
|
requestId: 0890cfb8f4278217bd457b49ce572265
|
|
status: 422
|
|
invalidFields:
|
|
- name: exchangeCalculations[0].sourceAmount.currency
|
|
message: The currency is invalid.
|
|
- name: exchangeCalculations[0].sourceAmount.value
|
|
message: The value can't be negative.
|
|
x-methodName: calculate
|
|
x-sortIndex: 1
|
|
components:
|
|
schemas:
|
|
Amount:
|
|
required:
|
|
- currency
|
|
- value
|
|
type: object
|
|
properties:
|
|
currency:
|
|
type: string
|
|
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes).
|
|
value:
|
|
type: integer
|
|
description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).
|
|
format: int64
|
|
CalculateRateRequest:
|
|
required:
|
|
- exchangeCalculations
|
|
type: object
|
|
properties:
|
|
exchangeCalculations:
|
|
maxItems: 1000
|
|
minItems: 1
|
|
type: array
|
|
description: An array of objects, where each object defines a currency and
|
|
value for which you want to perform an exchange calculation.
|
|
items:
|
|
$ref: '#/components/schemas/CalculateRateRequestItem'
|
|
description: The request to calculate an amount in a different currency.
|
|
CalculateRateRequestItem:
|
|
required:
|
|
- exchangeSide
|
|
- sourceAmount
|
|
- targetCurrency
|
|
- type
|
|
type: object
|
|
properties:
|
|
exchangeSide:
|
|
description: 'The operation performed on the source amount. Possible values:
|
|
|
|
* **buy**
|
|
|
|
* **sell**'
|
|
$ref: '#/components/schemas/ExchangeSide'
|
|
sourceAmount:
|
|
description: An object specifying the currency and value for which you want
|
|
to perform an exchange calculation.
|
|
$ref: '#/components/schemas/Amount'
|
|
targetCurrency:
|
|
type: string
|
|
description: The currency to which you want to convert the source amount.
|
|
type:
|
|
description: 'The type of transaction. Possible values:
|
|
|
|
* **splitPayment**: for payments
|
|
|
|
* **splitRefund**: for refunds'
|
|
$ref: '#/components/schemas/RateType'
|
|
description: The request parameters required to calculate an amount in a different
|
|
currency.
|
|
ExchangeSide:
|
|
type: string
|
|
enum:
|
|
- buy
|
|
- sell
|
|
RateType:
|
|
type: string
|
|
enum:
|
|
- splitPayment
|
|
- balanceConversion
|
|
- transfer
|
|
- splitRefund
|
|
CalculateRateResponse:
|
|
type: object
|
|
properties:
|
|
exchangeCalculations:
|
|
type: array
|
|
description: An array of objects, where each object returns a currency and
|
|
value for which you performed an exchange calculation. You can use the
|
|
calculated amounts in your payment requests.
|
|
items:
|
|
$ref: '#/components/schemas/CalculateRateResponseItem'
|
|
description: The response returned when you calculate an amount in a different
|
|
currency.
|
|
CalculateRateResponseItem:
|
|
type: object
|
|
properties:
|
|
appliedExchangeRate:
|
|
type: number
|
|
description: The exchange rate to convert the source currency to the target
|
|
currency. This includes Adyen's markup.
|
|
exchangeSide:
|
|
type: string
|
|
description: 'The operation performed on the source amount. Possible values:
|
|
|
|
* **buy**
|
|
|
|
* **sell**'
|
|
sourceAmount:
|
|
description: The currency of the amount you converted (the source amount).
|
|
$ref: '#/components/schemas/Amount'
|
|
targetAmount:
|
|
description: An object specifying the currency and value to which you want
|
|
to convert the source amount (the target amount).
|
|
$ref: '#/components/schemas/Amount'
|
|
type:
|
|
type: string
|
|
description: 'The type of transaction. Possible values:
|
|
|
|
* **splitPayment**: for payments
|
|
|
|
* **splitRefund**: for refunds'
|
|
description: The response parameters returned when you calculate an amount in
|
|
a different currency.
|
|
DefaultErrorResponseEntity:
|
|
type: object
|
|
properties:
|
|
detail:
|
|
type: string
|
|
description: A human-readable explanation specific to this occurrence of
|
|
the problem.
|
|
errorCode:
|
|
type: string
|
|
description: Unique business error code.
|
|
instance:
|
|
type: string
|
|
description: A URI that identifies the specific occurrence of the problem
|
|
if applicable.
|
|
invalidFields:
|
|
type: array
|
|
description: Array of fields with validation errors when applicable.
|
|
items:
|
|
$ref: '#/components/schemas/InvalidField'
|
|
requestId:
|
|
type: string
|
|
description: The unique reference for the request.
|
|
status:
|
|
type: integer
|
|
description: The HTTP status code.
|
|
format: int32
|
|
title:
|
|
type: string
|
|
description: A short, human-readable summary of the problem type.
|
|
type:
|
|
type: string
|
|
description: A URI that identifies the validation error type. It points
|
|
to human-readable documentation for the problem type.
|
|
description: Standardized error response following RFC-7807 format
|
|
externalDocs:
|
|
url: https://www.rfc-editor.org/rfc/rfc7807
|
|
InvalidField:
|
|
required:
|
|
- message
|
|
- name
|
|
- value
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The field that has an invalid value.
|
|
value:
|
|
type: string
|
|
description: The invalid value.
|
|
message:
|
|
type: string
|
|
description: Description of the validation error.
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
name: X-API-Key
|
|
in: header
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
|