{
  "openapi": "3.0.1",
  "info": {
    "title": "Pay Later OpenAPI specification",
    "description": "Pay Later allows shoppers to postpone the due date of an open invoice transaction between 14 and 150 days. Shoppers may use Pay Later to prevent getting dunned. It gives them the ability to plan their payments more individually. Charges apply when using this feature.<br /><br /> The Pay Later API enables sellers to integrate this functionality into their frontends. The Pay Later API offers endpoints to check the Pay Later status of a purchase order and to book a Pay Later option. By using the Pay Later API shops can offer their customers                         greater payment flexibility when paying by open invoice while keeping them inside their own frontends. <br /><br /> Booked Pay Later options can be withdraw within 14 days. Therefore the shopper can use one of the channels referenced in [Ratepay Pay Later Terms of Use](https://www.ratepay.com/legal-paylater/).",
    "version": "version 1"
  },
  "servers": [
    {
      "url": "https://api.ratepay.com",
      "description": "Production environment"
    }
  ],
  "security": [
    {
      "Bearer Authentication": []
    }
  ],
  "paths": {
    "/order/paylater/v1/{transaction_id}/status": {
      "get": {
        "summary": "Pay Later Status",
        "description": "Get Pay Later status for one order",
        "operationId": "getStatusForOrder",
        "parameters": [
          {
            "name": "transaction_id",
            "example": "12-34567890123456789",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          },
          {
            "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns Pay Later status for the given transaction_id.",
            "content": {
              "application/json;charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalStatusDto"
                }
              }
            }
          },
          "404": {
            "description": "Is returned if the transaction_id is unknown."
          },
          "405": {
            "description": "Is returned if this endpoint is called with a request method other than GET."
          },
          "406": {
            "description": "Is returned if the request accept header does not specify JSON as an accepted content type for the response."
          },
          "415": {
            "description": "Is returned if the request does not contain content type headers or if the request content type is anything other than JSON."
          },
          "500": {
            "description": "Is returned in case of a technical server error at Ratepay. Try again later."
          }
        }
      }
    },
    "/order/paylater/v1/{transaction_id}/offers": {
      "get": {
        "summary": "Pay Later Offers",
        "description": "Get available Pay Later offers for one order",
        "operationId": "getOffersForOrder",
        "parameters": [
          {
            "name": "transaction_id",
            "example": "12-34567890123456789",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          },
          {
            "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns a list of the available Pay Later options for the given transaction_id.",
            "content": {
              "application/json;charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalOfferDto"
                }
              }
            }
          },
          "404": {
            "description": "Is returned if the transaction_id is unknown."
          },
          "405": {
            "description": "Is returned if this endpoint is called with a request method other than GET."
          },
          "406": {
            "description": "Is returned if the request accept header does not specify JSON as an accepted content type for the response."
          },
          "409": {
            "description": "Is returned if Pay Later is not available, has already been booked or has been withdrawn for the given transaction_id. To avoid this error, check with the Pay Later status endpoint whether Pay Later is available for the order before calling this endpoint."
          },
          "415": {
            "description": "Is returned if the request does not contain content type headers or if the request content type is anything other than JSON."
          },
          "500": {
            "description": "Is returned in case of a technical server error at Ratepay. Try again later."
          }
        }
      }
    },
    "/order/paylater/v1/{transaction_id}": {
      "post": {
        "summary": "Booking Pay Later",
        "description": "Book a Pay Later offer for one order",
        "operationId": "createBooking",
        "parameters": [
          {
            "name": "transaction_id",
            "description": "The transaction id of the order for which Pay Later should be booked. (The Ratepay Gateway returns this when an order is created.",
            "example": "12-34567890123456789",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json"
            }
          },
          {
            "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"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json;charset=UTF-8": {
              "schema": {
                "$ref": "#/components/schemas/ExternalBookingRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Is returned if Pay Later has been successfully booked. The response contains the details of the booked Pay Later offer and the booking timestamp.",
            "content": {
              "application/json;charset=UTF-8": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalBookingConfirmationDto"
                }
              }
            }
          },
          "400": {
            "description": "Is returned if the request body contains an unknown offer_id or the offer_id parameter is missing."
          },
          "404": {
            "description": "Is returned if the transaction_id is unknown."
          },
          "405": {
            "description": "Is returned if this endpoint is called with a request method other than GET."
          },
          "406": {
            "description": "Is returned if the request accept header does not specify JSON as an accepted content type for the response."
          },
          "409": {
            "description": "Is returned if Pay Later is not available, has already been booked or has been withdrawn or the selected offer is not available for the given transaction_id. To avoid this error, check with the Pay Later status endpoint whether Pay Later is available for the order before calling this endpoint."
          },
          "413": {
            "description": "Is returned if the request is too large, e. g. a very large offer_id is set as the payload. This error cannot happen if an offer_id returned by the Pay Later Offers endpoint is used."
          },
          "415": {
            "description": "Is returned if the request does not contain content type headers or if the request content type is anything other than JSON."
          },
          "500": {
            "description": "Is returned in case of a technical server error at Ratepay. Try again later."
          }
        }
      }
    }
  },
  "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": {
      "ExternalBookingRequestDto": {
        "required": [
          "offer_id"
        ],
        "type": "object",
        "properties": {
          "offer_id": {
            "type": "string",
            "description": "The `offer_id` of the Pay Later offer to book as returned by the Pay Later Offers endpoint.",
            "example": "payl-1"
          }
        }
      },
      "ExternalBookingConfirmationDto": {
        "type": "object",
        "properties": {
          "delta_due_date": {
            "type": "integer",
            "format": "int32",
            "description": "The amount of days that the due date of the current order is postponed, i.e. the delta that comes on top of `original_due_date` (e.g. 14 days). Unit: days.",
            "example": 14
          },
          "fee": {
            "type": "number",
            "description": "The Pay Later fee for the booked Pay Later offer.",
            "example": 1.95
          },
          "currency": {
            "type": "string",
            "description": "The currency of the Pay Later fee, e.g. `EUR` (ISO 4217 alphabetic currency code, 3 chars).",
            "example": "EUR"
          },
          "original_due_date": {
            "type": "string",
            "format": "date",
            "description": "The original due date before Pay Later had been booked for the current order (ISO 8601, `YYYY-MM-DD`).",
            "example": "2020-03-14"
          },
          "new_due_date": {
            "type": "string",
            "format": "date",
            "description": " The new due date after booking Pay Later (ISO 8601, `YYYY-MM-DD`). This is `original_due_date + delta_due_date`.",
            "example": "2020-03-28"
          },
          "booking_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when Pay Later was booked for the current order (ISO 8601, `YYYY-MM-DDThh:mm:ss.ffffff+hh:mm`).",
            "example": "2020-03-13T16:42:59.974067+01:00"
          }
        }
      },
      "ExternalOfferDto": {
        "type": "object",
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "The transaction id as specified in the URI",
            "example": "12-34567890123456789"
          },
          "current_due_date": {
            "type": "string",
            "format": "date",
            "description": "The current due date of the order before booking Pay Later (ISO 8601, YYYY-MM-DD).",
            "example": "2020-03-14"
          },
          "pay_Later_offers": {
            "type": "array",
            "description": "A list containing all Pay Later offers for the order.",
            "items": {
              "$ref": "#/components/schemas/PayLaterOfferDto"
            }
          }
        }
      },
      "PayLaterOfferDto": {
        "type": "object",
        "properties": {
          "offer_id": {
            "type": "string",
            "description": "Identifies one Pay Later offer.",
            "example": "payl-1"
          },
          "price": {
            "type": "number",
            "description": "The price to book this Pay Later offer.",
            "example": 1.95
          },
          "currency": {
            "type": "string",
            "description": "The currency of the Pay Later price, e.g. `EUR` (ISO 4217 alphabetic currency code, 3 chars).",
            "example": "EUR"
          },
          "delta_due_date": {
            "type": "integer",
            "format": "int32",
            "description": "The amount of days that the current due date will be postponed if this Pay Later offer is booked, i.e. the delta that comes on top of the current due date (e.g. 14 days). Unit: days.",
            "example": 14
          },
          "new_due_date": {
            "type": "string",
            "format": "date",
            "description": "The new due date for this order if this Pay Later offer is booked (ISO 8601, `YYYY-MM-DD`). This is `current_due_date + delta_due_date`.",
            "example": "2020-03-28"
          },
          "available": {
            "type": "string",
            "description": "Availability of offer. Possible values: `AVAILABLE`, `NOT_AVAILABLE`",
            "enum": [
              "AVAILABLE",
              "NOT_AVAILABLE"
            ],
            "example": "NOT_AVAILABLE"
          }
        }
      },
      "ExternalBookingDto": {
        "type": "object",
        "description": "Contains Pay Later booking information. Is only available if `pay_later_status` is `ALREADY_BOOKED` or `ALREADY_WITHDRAWN`",
        "properties": {
          "fee": {
            "type": "number",
            "description": "The Pay Later fee for the given order for which Pay Later was booked",
            "example": 1.95
          },
          "currency": {
            "type": "string",
            "description": "The currency of the Pay Later fee, e.g. `EUR` (ISO 4217 alphabetic currency code, 3 chars)",
            "example": "EUR"
          },
          "delta_due_date": {
            "type": "integer",
            "format": "int32",
            "description": "The number of days that the due date is moved with Pay Later",
            "example": 14
          },
          "original_due_date": {
            "type": "string",
            "format": "date",
            "description": "The original due date before booking Pay Later (ISO 8601, `YYYY-MM-DD`). This is the current due date if Pay Later has been withdrawn.",
            "example": "2020-02-01"
          },
          "updated_due_date": {
            "type": "string",
            "format": "date",
            "description": "The due date after booking Pay Later (ISO 8601, `YYYY-MM-DD`). This is the current due date if Pay Later has been booked and not withdrawn.",
            "example": "2020-02-15"
          },
          "booking_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when Pay Later was booked (ISO 8601, `YYYY-MM-DDThh:mm:ss.ffffff+hh:mm`). This is also set if Pay Later has been withdrawn",
            "example": "2020-02-05T16:42:59.974067+01:00"
          },
          "withdrawal_date": {
            "type": "string",
            "format": "date",
            "description": "The date at which the Pay Later withdrawal request was received by Ratepay (ISO 8601, `YYYY-MM-DD`). This field is only available if `pay_later_status` is `ALREADY_WITHDRAWN`.",
            "example": "2020-02-06"
          }
        }
      },
      "ExternalStatusDto": {
        "type": "object",
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "The transaction id as specified in the URL",
            "example": "12-34567890123456789"
          },
          "pay_later_status": {
            "type": "string",
            "description": "Pay Later status for the current order. Possible values:<br /><br />- `AVAILABLE` = Pay Later can be booked for the current order<br />- `NOT_AVAILABLE` = Pay Later cannot be booked for the current order<br />- `ALREADY_BOOKED` = Pay Later has been booked for the current order and cannot be booked again<br />- `ALREADY_WITHDRAWN` = Pay Later was booked and withdrawn for the current order and cannot be booked again",
            "enum": [
              "AVAILABLE",
              "NOT_AVAILABLE",
              "ALREADY_BOOKED",
              "ALREADY_WITHDRAWN"
            ],
            "example": "ALREADY_WITHDRAWN"
          },
          "booking": {
            "$ref": "#/components/schemas/ExternalBookingDto"
          }
        }
      }
    }
  }
}