A separate first-party Token.io OpenAPI 3.0.0 document (version 1.0.2) covering refund registration, initiation, retrieval and signing, plus certificate upload. Retrieved 2026-09-17 through Token.io's own MCP server at https://docs.token.io/mcp; it names https://api.token.io/v2 as the Token.io API server and support@token.io as its contact.
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/token-io-refunds-bnpp-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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.0.0",
"info": {
"title": "Token.io Refunds API",
"description": "Token.io Payments REST API 2.0 <br/><br/>Token.io Support: <a href=\"mailto:support@token.io\">support@token.io</a><br/><br/>The Token.io Payments API enables you to connect securely with banks. Using our API you can handle registration, posting, and retrieval of refunds associated with original transaction account information.<br/>For more information see our <a href=\"https://developer.token.io/bnpp_rest_api_doc/content/e-rest/pis/reverse-payment-bnpp.htm\" target=\"_blank\">developer documentation</a>.",
"version": "1.0.2"
},
"servers": [
{
"url": "https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2",
"description": "SwaggerHub API Auto Mocking"
},
{
"url": "https://api.token.io/v2",
"description": "Token.io API server"
}
],
"tags": [
{
"name": "Refunds",
"description": "Using these endpoints you can handle registration, posting, and retrieval of refunds associated with original transaction account information."
}
],
"paths": {
"/refund/registrations": {
"post": {
"tags": [
"Refunds"
],
"summary": "Register a debtor account for refund",
"description": "Registers a debtor account for refund processing. </br> If the bank or provider returns any additional credentials for further refund payments, Token.io will store them in the Hardware Security Module (HSM).",
"operationId": "RefundRegister",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund_registrations_body"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PayoutRegisterResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
}
},
"/refund/registrations/{registrationId}": {
"get": {
"tags": [
"Refunds"
],
"summary": "Retrieve refund registration information",
"description": "Retrieves the current refund registration information by registration id.",
"operationId": "GetRefundRegistration",
"parameters": [
{
"name": "registrationId",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"description": "The registration id.",
"example": "your registration id"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPayoutRegistrationResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
},
"delete": {
"tags": [
"Refunds"
],
"summary": "Delete refund registration information",
"description": "Deletes refund registration information by registration id.",
"operationId": "DeleteRefundRegistration",
"parameters": [
{
"name": "registrationId",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"description": "The registration id.",
"example": "your registration id"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
}
},
"/refunds": {
"get": {
"tags": [
"Refunds"
],
"summary": "Retrieve refunds",
"description": "Retrieves a complete or filtered list of refunds.",
"operationId": "GetRefunds",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of records to return.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"format": "int32"
},
"example": 10
},
{
"name": "offset",
"in": "query",
"description": "The offset from the previous page.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
},
"example": ""
},
{
"name": "startDate",
"in": "query",
"description": "Lower bound for a refund creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only refunds created at or after the given date will be returned.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
},
"example": "2010-01-01"
},
{
"name": "endDate",
"in": "query",
"description": "Upper bound for a refund creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only refunds created at or before the given date will be returned.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
},
"example": "2010-01-01"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundsResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
},
"post": {
"tags": [
"Refunds"
],
"summary": "Initiate a refund",
"description": "Initiates a refund. After the refund is settled, the refund status of the original transfer will be updated. <br/> The debtor field can be optional if you're using the debtor in registration. The creditor field can be optional if the information is available in the original payment.",
"operationId": "InitiateRefund",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refunds_body"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
}
},
"/refunds/signature": {
"post": {
"tags": [
"Refunds"
],
"summary": "Build the payload a merchant has to sign for a refund",
"description": "Returns the provider payload the merchant has to sign before calling <code>POST /refunds</code>. Stateless: no refund is created and nothing is persisted by this call. </br> The merchant signs the returned <code>payloadToSign</code> and submits the signature back in the <code>signature</code> field of the <code>initiation</code> on the subsequent <code>POST /refunds</code> call.",
"operationId": "GenerateRefundSigningPayload",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refunds_body"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateRefundSigningPayloadResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"deprecated": false,
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
],
"x-hideTryItPanel": true
}
},
"/refunds/{id}": {
"get": {
"tags": [
"Refunds"
],
"summary": "Retrieve a Refund",
"description": "Retrieves a refund by the id.",
"operationId": "GetRefund",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"description": "The refund id.",
"example": "your refund id"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_403"
}
}
}
},
"404": {
"description": "The requested entity, such as a payment, was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_404"
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_429"
}
}
}
},
"500": {
"description": "An unexpected or internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_500"
}
}
}
},
"501": {
"description": "The operation was not implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_501"
}
}
}
},
"503": {
"description": "Service is unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_503"
}
}
}
},
"504": {
"description": "Gateway has timed out",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_504"
}
}
}
}
},
"security": [
{
"BasicAuth": []
},
{
"Bearer": []
}
]
}
},
"/transfers/{id}/refunds": {
"get": {
"tags": [
"Refunds"
],
"summary": "Retrieve all refunds by transfer",
"description": "Retrieves all the refunds associated with the given transfer.",
"operationId": "GetTransferRefunds",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of records to return.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer",
"format": "int32"
},
"example": 10
},
{
"name": "offset",
"in": "query",
"description": "The offset from the previous page.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
},
"example": ""
},
{
"name": "id",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string",
"description": "The transfer id.",
"example": "your transfer id"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundsResponse"
}
}
}
},
"400": {
"description": "The client specified an invalid argument",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"401": {
"description": "The authorisation information is missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_response_400"
}
}
}
},
"403": {
"description": "Permission to access this endpoint is denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inline_respons
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/token-io/refs/heads/main/openapi/token-io-refunds-bnpp-openapi.json