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'
