callback-urls-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Event Notification API Specification - ASPSP Endpoints",
    "description": "Swagger for Event Notification API Specification - ASPSP Endpoints",
    "termsOfService": "https://www.openbanking.org.uk/terms",
    "contact": {
      "name": "Service Desk",
      "email": "ServiceDesk@openbanking.org.uk"
    },
    "license": {
      "name": "open-licence",
      "url": "https://www.openbanking.org.uk/open-licence"
    },
    "version": "v3.1.6"
  },
  "servers": [
    {
      "url": "/open-banking/v3.1"
    }
  ],
  "paths": {
    "/callback-urls": {
      "get": {
        "tags": [
          "Callback URLs"
        ],
        "summary": "Read all callback URLs",
        "parameters": [
          {
            "name": "x-fapi-interaction-id",
            "in": "header",
            "description": "An RFC4122 UID used as a correlation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "An Authorisation Token as per https://tools.ietf.org/html/rfc6750",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of callback URLs",
            "headers": {
              "x-jws-signature": {
                "description": "Header containing a detached JWS signature of the body of the payload.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlsResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlsResponse1"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {}
          },
          "403": {
            "description": "Forbidden",
            "content": {}
          },
          "404": {
            "description": "Not found",
            "content": {}
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {}
          },
          "406": {
            "description": "Not Acceptable",
            "content": {}
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "Retry-After": {
                "description": "Number in seconds to wait",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {}
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          }
        },
        "security": [
          {
            "TPPOAuth2Security": [
              "accounts",
              "fundsconfirmations",
              "payments"
            ]
          }
        ]
      },
      "post": {
        "tags": [
          "Callback URLs"
        ],
        "summary": "Create a callback URL",
        "parameters": [
          {
            "name": "x-fapi-interaction-id",
            "in": "header",
            "description": "An RFC4122 UID used as a correlation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "An Authorisation Token as per https://tools.ietf.org/html/rfc6750",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-jws-signature",
            "in": "header",
            "description": "Header containing a detached JWS signature of the body of the payload.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Create an Callback URI",
          "content": {
            "application/json; charset=utf-8": {
              "schema": {
                "$ref": "#/components/schemas/OBCallbackUrl1"
              }
            },
            "application/jose+jwe": {
              "schema": {
                "$ref": "#/components/schemas/OBCallbackUrl1"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Callback URL created",
            "headers": {
              "x-jws-signature": {
                "description": "Header containing a detached JWS signature of the body of the payload.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlResponse1"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {}
          },
          "403": {
            "description": "Forbidden",
            "content": {}
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {}
          },
          "406": {
            "description": "Not Acceptable",
            "content": {}
          },
          "415": {
            "description": "Unsupported Media Type",
            "content": {}
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "Retry-After": {
                "description": "Number in seconds to wait",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {}
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          }
        },
        "security": [
          {
            "TPPOAuth2Security": [
              "accounts",
              "fundsconfirmations",
              "payments"
            ]
          }
        ],
        "x-codegen-request-body-name": "OBCallbackUrl1Param"
      }
    },
    "/callback-urls/{CallbackUrlId}": {
      "put": {
        "tags": [
          "Callback URLs"
        ],
        "summary": "Amend a callback URI",
        "parameters": [
          {
            "name": "CallbackUrlId",
            "in": "path",
            "description": "CallbackUrlId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-fapi-interaction-id",
            "in": "header",
            "description": "An RFC4122 UID used as a correlation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "An Authorisation Token as per https://tools.ietf.org/html/rfc6750",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-jws-signature",
            "in": "header",
            "description": "Header containing a detached JWS signature of the body of the payload.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Create an Callback URI",
          "content": {
            "application/json; charset=utf-8": {
              "schema": {
                "$ref": "#/components/schemas/OBCallbackUrl1"
              }
            },
            "application/jose+jwe": {
              "schema": {
                "$ref": "#/components/schemas/OBCallbackUrl1"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Callback URL changed",
            "headers": {
              "x-jws-signature": {
                "description": "Header containing a detached JWS signature of the body of the payload.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBCallbackUrlResponse1"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {}
          },
          "403": {
            "description": "Forbidden",
            "content": {}
          },
          "404": {
            "description": "Not found",
            "content": {}
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {}
          },
          "406": {
            "description": "Not Acceptable",
            "content": {}
          },
          "415": {
            "description": "Unsupported Media Type",
            "content": {}
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "Retry-After": {
                "description": "Number in seconds to wait",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {}
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          }
        },
        "security": [
          {
            "TPPOAuth2Security": [
              "accounts",
              "fundsconfirmations",
              "payments"
            ]
          }
        ],
        "x-codegen-request-body-name": "OBCallbackUrl1Param"
      },
      "delete": {
        "tags": [
          "Callback URLs"
        ],
        "summary": "Delete a callback URI",
        "parameters": [
          {
            "name": "CallbackUrlId",
            "in": "path",
            "description": "CallbackUrlId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-fapi-interaction-id",
            "in": "header",
            "description": "An RFC4122 UID used as a correlation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "An Authorisation Token as per https://tools.ietf.org/html/rfc6750",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Callback URL changed",
            "content": {}
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {}
          },
          "403": {
            "description": "Forbidden",
            "content": {}
          },
          "404": {
            "description": "Not found",
            "content": {}
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {}
          },
          "406": {
            "description": "Not Acceptable",
            "content": {}
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "Retry-After": {
                "description": "Number in seconds to wait",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {}
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              },
              "application/jose+jwe": {
                "schema": {
                  "$ref": "#/components/schemas/OBErrorResponse1"
                }
              }
            }
          }
        },
        "security": [
          {
            "TPPOAuth2Security": [
              "accounts",
              "fundsconfirmations",
              "payments"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "OBCallbackUrl1": {
        "required": [
          "Data"
        ],
        "type": "object",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/OBCallbackUrlData1"
          }
        }
      },
      "OBCallbackUrlData1": {
        "required": [
          "Url",
          "Version"
        ],
        "type": "object",
        "properties": {
          "Url": {
            "type": "string",
            "description": "Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to."
          },
          "Version": {
            "maxLength": 10,
            "minLength": 1,
            "type": "string",
            "description": "Version for the event notification."
          }
        }
      },
      "OBCallbackUrlResponse1": {
        "required": [
          "Data",
          "Links",
          "Meta"
        ],
        "type": "object",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/OBCallbackUrlResponseData1"
          },
          "Links": {
            "$ref": "#/components/schemas/Links"
          },
          "Meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "OBCallbackUrlResponseData1": {
        "required": [
          "CallbackUrlId",
          "Url",
          "Version"
        ],
        "type": "object",
        "properties": {
          "CallbackUrlId": {
            "maxLength": 40,
            "minLength": 1,
            "type": "string",
            "description": "Unique identification as assigned by the ASPSP to uniquely identify the callback url resource."
          },
          "Url": {
            "type": "string",
            "description": "Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to."
          },
          "Version": {
            "maxLength": 10,
            "minLength": 1,
            "type": "string",
            "description": "Version for the event notification."
          }
        }
      },
      "OBCallbackUrlsResponse1": {
        "required": [
          "Data",
          "Links",
          "Meta"
        ],
        "type": "object",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/OBCallbackUrlsResponseData1"
          },
          "Links": {
            "$ref": "#/components/schemas/Links"
          },
          "Meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "OBCallbackUrlsResponseData1": {
        "type": "object",
        "properties": {
          "CallbackUrl": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OBCallbackUrlResponseData1"
            }
          }
        }
      },
      "OBError1": {
        "required": [
          "ErrorCode",
          "Message"
        ],
        "type": "object",
        "properties": {
          "ErrorCode": {
            "maxLength": 128,
            "minLength": 1,
            "type": "string",
            "description": "Low level textual error code, e.g., UK.OBIE.Field.Missing"
          },
          "Message": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string",
            "description": "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nOBIE doesn't standardise this field"
          },
          "Path": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string",
            "description": "Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency"
          },
          "Url": {
            "type": "string",
            "description": "URL to help remediate the problem, or provide more information, or to API Reference, or help etc"
          }
        }
      },
      "OBErrorResponse1": {
        "required": [
          "Code",
          "Errors",
          "Message"
        ],
        "type": "object",
        "properties": {
          "Code": {
            "maxLength": 40,
            "minLength": 1,
            "type": "string",
            "description": "High level textual error code, to help categorize the errors."
          },
          "Id": {
            "maxLength": 40,
            "minLength": 1,
            "type": "string",
            "description": "A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors."
          },
          "Message": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string",
            "description": "Brief Error message, e.g., 'There is something wrong with the request parameters provided'"
          },
          "Errors": {
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OBError1"
            }
          }
        },
        "description": "An array of detail error codes, and messages, and URLs to documentation to help remediation."
      },
      "ISODateTime": {
        "type": "string",
        "description": "All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00",
        "format": "date-time"
      },
      "Links": {
        "required": [
          "Self"
        ],
        "type": "object",
        "properties": {
          "Self": {
            "type": "string",
            "format": "uri"
          },
          "First": {
            "type": "string",
            "format": "uri"
          },
          "Prev": {
            "type": "string",
            "format": "uri"
          },
          "Next": {
            "type": "string",
            "format": "uri"
          },
          "Last": {
            "type": "string",
            "format": "uri"
          }
        },
        "description": "Links relevant to the payload"
      },
      "Meta": {
        "title": "MetaData",
        "type": "object",
        "properties": {
          "TotalPages": {
            "type": "integer",
            "format": "int32"
          },
          "FirstAvailableDateTime": {
            "$ref": "#/components/schemas/ISODateTime"
          },
          "LastAvailableDateTime": {
            "$ref": "#/components/schemas/ISODateTime"
          }
        },
        "description": "Meta Data relevant to the payload"
      }
    },
    "responses": {
      "200CallbackUrlsChanged": {
        "description": "Callback URL changed",
        "headers": {
          "x-jws-signature": {
            "description": "Header containing a detached JWS signature of the body of the payload.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlResponse1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlResponse1"
            }
          }
        }
      },
      "200CallbackUrlsRead": {
        "description": "An array of callback URLs",
        "headers": {
          "x-jws-signature": {
            "description": "Header containing a detached JWS signature of the body of the payload.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlsResponse1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlsResponse1"
            }
          }
        }
      },
      "201CallbackUrlsCreated": {
        "description": "Callback URL created",
        "headers": {
          "x-jws-signature": {
            "description": "Header containing a detached JWS signature of the body of the payload.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlResponse1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrlResponse1"
            }
          }
        }
      },
      "204CallbackUrlsDeleted": {
        "description": "Callback URL changed",
        "content": {}
      },
      "400ErrorResponse": {
        "description": "Bad request",
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBErrorResponse1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBErrorResponse1"
            }
          }
        }
      },
      "401ErrorResponse": {
        "description": "Unauthorized",
        "content": {}
      },
      "403ErrorResponse": {
        "description": "Forbidden",
        "content": {}
      },
      "404ErrorResponse": {
        "description": "Not found",
        "content": {}
      },
      "405ErrorResponse": {
        "description": "Method Not Allowed",
        "content": {}
      },
      "406ErrorResponse": {
        "description": "Not Acceptable",
        "content": {}
      },
      "415ErrorResponse": {
        "description": "Unsupported Media Type",
        "content": {}
      },
      "429ErrorResponse": {
        "description": "Too Many Requests",
        "headers": {
          "Retry-After": {
            "description": "Number in seconds to wait",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {}
      },
      "500ErrorResponse": {
        "description": "Internal Server Error",
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBErrorResponse1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBErrorResponse1"
            }
          }
        }
      }
    },
    "parameters": {
      "CallbackUrlId": {
        "name": "CallbackUrlId",
        "in": "path",
        "description": "CallbackUrlId",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "x-fapi-interaction-id-Param": {
        "name": "x-fapi-interaction-id",
        "in": "header",
        "description": "An RFC4122 UID used as a correlation id.",
        "schema": {
          "type": "string"
        }
      },
      "AuthorizationParam": {
        "name": "Authorization",
        "in": "header",
        "description": "An Authorisation Token as per https://tools.ietf.org/html/rfc6750",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "x-jws-signature-Param": {
        "name": "x-jws-signature",
        "in": "header",
        "description": "Header containing a detached JWS signature of the body of the payload.",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "requestBodies": {
      "OBCallbackUrl1Param": {
        "description": "Create an Callback URI",
        "content": {
          "application/json; charset=utf-8": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrl1"
            }
          },
          "application/jose+jwe": {
            "schema": {
              "$ref": "#/components/schemas/OBCallbackUrl1"
            }
          }
        },
        "required": true
      }
    },
    "securitySchemes": {
      "TPPOAuth2Security": {
        "type": "oauth2",
        "description": "TPP client credential authorisation flow with the ASPSP",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://authserver.example/token",
            "scopes": {
              "accounts": "Ability to read Accounts information",
              "fundsconfirmations": "Ability to confirm funds",
              "payments": "Generic payment scope"
            }
          }
        }
      }
    }
  }
}