{
  "openapi": "3.0.1",
  "info": {
    "title": "Bank Account Management Service OpenAPI specification",
    "description": "The Bank Account Management Service enables merchants to store bank account data of their customers easily and highly secured at                       Ratepay. The stored bank account data can be used on the merchant's website or within backoffice orders to simplify future purchases.  The Bank Account Management Service offers a REST API to store, retrieve and delete customer bank account data. The API uses JSON as                       data exchange format..",
    "version": "version 1"
  },
  "servers": [
    {
      "url": "https://api-integration.ratepay.com/shop/consumer/v1",
      "description": "Integration environment"
    },
    {
      "url": "https://api.ratepay.com/shop/consumer/v1",
      "description": "Production environment"
    }
  ],
  "security": [
    {
      "Bearer Authentication": []
    }
  ],
  "paths": {
    "/partners/{partner_profile_id}/consumer/{shop_buyer_id}/bank-accounts": {
      "get": {
        "summary": "Get stored bank account by shop buyer id",
        "description": "Retrieve a list of bank accounts stored for a specific buyer. Currently, the service stores one bank account per buyer. Thus,                             the returned list contains max. one bank account.",
        "operationId": "getBankAccounts",
        "parameters": [
          {
            "name": "partner_profile_id",
            "in": "path",
            "description": "partner profile id provided by Ratepay.",
            "example": "MYSHOP_PR_DE",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shop_buyer_id",
            "in": "path",
            "description": "unique id assigned to the buyer by the merchant",
            "required": true,
            "schema": {
              "type": "string",
              "example": "customer_1"
            }
          },
          {
            "name": "Authorization",
            "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully returned requested data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "401": {
            "description": "partner profile id doesn't belong to the asking shop",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "404": {
            "description": "Unknown merchant consumer id",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "406": {
            "description": "Data format not supported (JSON only)",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "413": {
            "description": "Request entity too large",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "500": {
            "description": "Internal server error. Try again later.",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      },
      "post": {
        "summary": "Store bank account",
        "description": "Store bank account data for a specific buyer. Currently, only one bank account can be stored              per buyer. Subsequent calls to that endpoint for the same buyer will overwrite existing bank account data.",
        "operationId": "storeBankAccount",
        "parameters": [
          {
            "name": "partner_profile_id",
            "in": "path",
            "description": "partner profile id provided by Ratepay",
            "example": "MYSHOP_PR_DE",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shop_buyer_id",
            "in": "path",
            "description": "unique id assigned to the consumer by the merchant",
            "required": true,
            "schema": {
              "type": "string",
              "example": "customer_1"
            }
          },
          {
            "name": "Authorization",
            "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          }
        ],
        "requestBody": {
          "description": "bank account data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BankAccount"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "bank account stored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "400": {
            "description": "data must contain IBAN and owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "401": {
            "description": "partner profile id doesn't belong to the asking shop",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "406": {
            "description": "Data format not supported (JSON only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "413": {
            "description": "Request entity too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported content type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "422": {
            "description": "Invalid IBAN or BIC",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountReference"
                }
              }
            }
          }
        }
      }
    },
    "/partners/{partner_profile_id}/consumer/{shop_buyer_id}/bank-accounts/{bank_account_reference}": {
      "delete": {
        "summary": "Delete bank account",
        "description": "Delete a stored bank account of a given buyer.",
        "operationId": "deleteBankAccount",
        "parameters": [
          {
            "name": "partner_profile_id",
            "in": "path",
            "description": "partner profile id provided by Ratepay",
            "example": "MYSHOP_PR_DE",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shop_buyer_id",
            "in": "path",
            "description": "unique id assigned to the buyer by the merchant",
            "example": "customer_1",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bank_account_reference",
            "in": "path",
            "description": "unique identifier for the bank account. This element can be retrieved by the GET request",
            "example": "226e7a20-5e1e-4f23-a56c-c8a851b190e7",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "bank account deleted"
          },
          "401": {
            "description": "partner profile id doesn't belong to the asking shop"
          },
          "404": {
            "description": "Unknown merchant consumer id"
          },
          "500": {
            "description": "Internal server error. Try again later."
          }
        }
      }
    },
    "/partners/{partner_profile_id}/shop-buyers/{shop_buyer_id}/bank-accounts/{bank_account_reference}": {
      "get": {
        "summary": "Get stored bank account by bank account reference",
        "description": "Retrieve a list of bank accounts stored for a specific bank account reference. Currently, the service stores one bank account per buyer. Thus, the returned list contains max. one bank account.",
        "operationId": "getBankAccountInternal",
        "parameters": [
          {
            "name": "partner_profile_id",
            "in": "path",
            "description": "partner profile id provided by Ratepay.",
            "example": "MYSHOP_PR_DE",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "shop_buyer_id",
            "in": "path",
            "description": "unique id assigned to the buyer by the merchant",
            "example": "customer_1",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bank_account_reference",
            "in": "path",
            "description": "the identifier of the bank account",
            "example": "226e7a20-5e1e-4f23-a56c-c8a851b190e7",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Authorization",
            "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {}
          }
        },
        "responses": {
          "200": {
            "description": "Successfully returned requested data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "401": {
            "description": "default response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "404": {
            "description": "Unknown merchant consumer id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "406": {
            "description": "Data format not supported (JSON only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "413": {
            "description": "Request entity too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccount"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Bearer Authentication": {
        "type": "http",
        "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "ErrorInfo": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "BankAccount": {
        "required": [
          "iban",
          "owner"
        ],
        "type": "object",
        "properties": {
          "bank_account_reference": {
            "type": "string",
            "description": "identifier of the bank account",
            "format": "uuid",
            "readOnly": true,
            "example": "8e3412b0-a334-4d0a-b132-7ab996d769ef"
          },
          "owner": {
            "maxLength": 1000,
            "minLength": 0,
            "type": "string",
            "description": "name of bank account owner (including first name and last name)",
            "example": "Jane Doe"
          },
          "iban": {
            "maxLength": 50,
            "minLength": 0,
            "type": "string",
            "description": "the international bank account number. Spaces are allowed, but not necessary.",
            "example": "DE07 1234 1234 1234 1234 12"
          },
          "bic": {
            "maxLength": 50,
            "minLength": 0,
            "type": "string",
            "description": "the bank identifier code",
            "example": "MARKDEFFXXX"
          }
        },
        "description": "bank account data"
      },
      "BankAccountReference": {
        "type": "object",
        "properties": {
          "bank_account_reference": {
            "type": "string",
            "description": "The `bank_account_reference` can be used in a payment request to identify the IBAN and BIC for the purchase.",
            "format": "uuid"
          }
        },
        "description": "reference to bank account data"
      }
    }
  }
}