openapi: 3.0.0
info:
  title: Rapid Payments
  description: Rapid Payments V2
  version: v2
servers:
  - url: https://pay-test.ean.com/v2
  - url: https://pay.ean.com/v2
tags:
  - name: Pay
    description: The Pay API allows you to register customer payment information for booking requests.
paths:
  /payments:
    post:
      operationId: registerPayment
      description: |
        Register a payment method to be used when making a booking. The response will contain a payment_token, which goes in the body of the create booking request.
      summary: Register Payment
      tags:
        - Pay
      security:
        - EgTokenAuth:
            - demand-solutions.cars
      parameters:
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/AcceptEncoding'
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/CustomerIpRequired'
        - $ref: '#/components/parameters/CustomerSessionId'
        - $ref: '#/components/parameters/UserAgent'
        - $ref: '#/components/parameters/BookTestHeader'
        - $ref: '#/components/parameters/RapidToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRegistrationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRegistrationResponse'
              examples:
                responses:
                  $ref: '#/components/examples/payment-201-success'
        '400':
          $ref: '#/components/responses/BadRequestInvalidInput400Error'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '426':
          $ref: '#/components/responses/Error426'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
components:
  securitySchemes:
    EgTokenAuth:
      type: oauth2
      description: this api uses Oauth2 with EGToken scheme
      flows:
        clientCredentials:
          tokenUrl: https://api.ean.com/identity/oauth2/v3/token
          scopes:
            demand-solutions.cars: allow access to cars api
  parameters:
    Accept:
      in: header
      name: Accept
      example: application/json
      description: |
        Specifies the response format that the client would like to receive back.
      required: true
      schema:
        type: string
        enum:
          - application/json
    AcceptEncoding:
      in: header
      name: Accept-Encoding
      example: gzip
      description: |
        Specifies the response encoding that the client would like to receive back.
      required: true
      schema:
        type: string
        enum:
          - gzip
    BookTestHeader:
      description: |
        Specifies what type of response type should be returned for testing the api.
      name: Test
      in: header
      required: false
      schema:
        type: string
        enum:
          - standard
          - service_unavailable
          - internal_server_error
          - price_mismatch
          - car_unavailable
    CustomerIpRequired:
      in: header
      name: Customer-Ip
      description: |
        IP address of the customer, as captured by your integration. Send IPV4 addresses only.

        Ensure your integration passes the customer's IP, not your own. This value helps determine their location and assign the correct payment gateway.

        Also used for fraud recovery and other important analytics.
      required: true
      schema:
        type: string
        format: ipv4
    ContentType:
      in: header
      name: Content-Type
      example: application/json
      description: |
        This parameter is to specify what format the request body is in. The only supported value is application/json.
      required: true
      schema:
        type: string
        enum:
          - application/json
    CustomerSessionId:
      in: header
      name: Customer-Session-Id
      description: |
        Insert your own unique value for each user session, beginning with the first API call.

        Continue to pass the same value for each subsequent API call during the user's session, using a new value for every new customer session.

        Including this value greatly eases our internal debugging process for issues with partner requests, as it explicitly links together request paths for individual user's session.
      required: false
      schema:
        type: string
    UserAgent:
      in: header
      name: User-Agent
      examples:
        Chrome:
          value: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36
        TravelNow:
          value: TravelNow/3.30.112
      description: |
        The `User-Agent` header string from the customer's request, as captured by your integration. 
        If you are building an application then the `User-Agent` value should be `{app name}/{app version}`.
      required: true
      schema:
        type: string
    RapidToken:
      in: query
      name: token
      description: |
        Provided as part of the link object and used to maintain state across calls. 
        This simplifies each subsequent call by limiting the amount of information required at each step and reduces the potential for errors. 
        Token values cannot be viewed or changed.
      required: true
      schema:
        type: string
  responses:
    BadRequestInvalidInput400Error:
      description: Bad Request
      headers:
        Rate-Limit-Day:
          description: Reserved for future use. Optional header for request capacity per day.
          schema:
            type: number
        Rate-Limit-Day-Remaining:
          description: Optional header for the remaining capacity, as a percentage, for the daily time window.
          schema:
            type: number
        Rate-Limit-Day-Reset:
          description: Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the daily capacity resets.
          schema:
            type: number
        Rate-Limit-Minute:
          description: Reserved for future use. Optional header for request capacity per minute.
          schema:
            type: number
        Rate-Limit-Minute-Remaining:
          description: Optional header for the remaining capacity, as a percentage, for the per minute time window.
          schema:
            type: number
        Rate-Limit-Minute-Reset:
          description: Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the per minute capacity resets.
          schema:
            type: number
        Rate-Limit-Reduction-Status:
          description: Optional header that indicates the state (inactive, active) of minute capacity reduction triggered once all daily capacity has been used.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/invalid-input'
    Error401:
      description: Unauthorized
      headers:
        WWW-Authenticate:
          description: Provides an example of the Authorization header.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/request-unauthenticated'
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/request-unauthorized'
    Error426:
      description: Upgrade Required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/upgrade-required'
    Error429:
      description: Too Many Requests
      headers:
        Rate-Limit-Day:
          description: Reserved for future use. Optional header for request capacity per day.
          schema:
            type: number
        Rate-Limit-Day-Remaining:
          description: Optional header for the remaining capacity, as a percentage, for the daily time window.
          schema:
            type: number
        Rate-Limit-Day-Reset:
          description: Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the daily capacity resets.
          schema:
            type: number
        Rate-Limit-Minute:
          description: Reserved for future use. Optional header for request capacity per minute.
          schema:
            type: number
        Rate-Limit-Minute-Remaining:
          description: Optional header for the remaining capacity, as a percentage, for the per minute time window.
          schema:
            type: number
        Rate-Limit-Minute-Reset:
          description: Optional header for the timestamp, as the number of milliseconds since the Unix Epoch, when the per minute capacity resets.
          schema:
            type: number
        Rate-Limit-Reduction-Status:
          description: Optional header that indicates the state (inactive, active) of minute capacity reduction triggered once all daily capacity has been used.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/too-many-requests'
    Error500:
      description: Unknown Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/unknown-internal-error'
    Error503:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            response:
              $ref: '#/components/examples/service-unavailable'
  schemas:
    PaymentRegistrationRequest:
      type: object
      required:
        - type
        - number
        - security_code
        - expiration_month
        - expiration_year
        - billing_contact
      properties:
        type:
          type: string
          description: Identifier for the type of payment.
          enum:
            - corporate_card
            - customer_card
            - virtual_card
        number:
          type: string
          description: Card number. Required for credit card transactions.
          example: '4111111111111111'
        security_code:
          type: string
          description: CVV/CSV code from the back of the customer's card. Required for credit card transactions.
          example: '123'
        expiration_month:
          type: string
          description: Two-digit month the credit card will expire. Required for credit card transactions.
          example: '5'
        expiration_year:
          type: string
          description: Year the credit card will expire. Required for credit card transactions.
          example: '2025'
        billing_contact:
          required:
            - given_name
            - family_name
            - email
            - phone
            - address
          properties:
            given_name:
              type: string
              description: First/given name of the payment type account holder. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
              example: John
            family_name:
              type: string
              description: Last/family name of the payment type account holder. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
              example: Doe
            email:
              type: string
              description: Email address for the customer. Must adhere to standard email format.
              example: smith@example.com
            phone:
              $ref: '#/components/schemas/PhoneRequest'
            address:
              type: object
              description: This must be a valid address.
              required:
                - line_1
                - city
                - postal_code
                - country_code
              properties:
                line_1:
                  type: string
                  description: First line of customer's street address. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: 123 Main St
                line_2:
                  type: string
                  description: Second line of customer's street address. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: Apt 1
                line_3:
                  type: string
                  description: Third line of customer's street address. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: Building C
                city:
                  type: string
                  description: Customer's city. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: Springfield
                state_province_code:
                  type: string
                  description: Customer's state or province code. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: IL
                postal_code:
                  type: string
                  description: Customer's postal code. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: '62704'
                country_code:
                  type: string
                  description: Customer's country code, in two-letter ISO 3166-1 alpha-2 format. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
                  example: US
        strong_customer_authentication:
          type: object
          properties:
            rapid:
              $ref: '#/components/schemas/RapidSCA'
            third_party:
              $ref: '#/components/schemas/ThirdPartySCA'
    PhoneRequest:
      type: object
      required:
        - country_code
        - number
      description: The entire phone number must be represented across the three fields in this object.
      properties:
        country_code:
          type: string
          description: The numerical portion of the country code from the phone number. Do not include the leading '+' character. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
          example: '1'
        area_code:
          type: string
          description: The area code of the phone number. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
          example: '487'
        number:
          type: string
          description: The remaining digits of the phone number. Special characters ("<", ">", "(", ")", and "&") entered in this field will be re-encoded.
          example: '5550077'
    RapidSCA:
      type: object
      properties:
        version:
          type: string
          description: Indicates the version of the payment authentication protocol used for the transaction.
          example: '1'
        browser_accept_header:
          type: string
          description: The types of content the customer's browser can accept, as provided by their browser during the booking process.
          example: '*/*'
        encoded_browser_metadata:
          type: string
          description: Encoded information about the customer's browser, used to help verify the payment.
          example: ZW5jb2RlZF9icm93c2VyX21ldGFkYXRh
        preferred_challenge_window_size:
          type: string
          description: The preferred window size that needs to be displayed to the customer.
          enum:
            - extra_small
            - small
            - medium
            - large
            - full_screen
        merchant_url:
          type: string
          description: URL of the merchant's website where the transaction is taking place.
          example: https://server.adomainname.net
        enrollment_date:
          type: string
          description: Date the payment account was enrolled in the cardholder's account with the merchant, in ISO 8601 format (YYYY-MM-DD).
          example: '2018-09-15'
        customer_account_details:
          type: object
          description: Details about the customer's account relevant to SCA.
          properties:
            authentication_method:
              type: string
              description: Mechanism used by the cardholder to authenticate to the merchant.
              enum:
                - guest
                - own_credentials
                - federated_id
                - issuer_credentials
                - third_party_authentication
                - fido_authentication
            authentication_timestamp:
              type: string
              description: Date and time in UTC of the cardholder authentication, in extended ISO 8601 format.
              example: '2018-02-12T11:59:00.000Z'
            create_date:
              type: string
              description: Date the cardholder opened the account with the merchant, in ISO 8601 format (YYYY-MM-DD).
              example: '2018-09-15'
            change_date:
              type: string
              description: Date the cardholder’s account with the merchant was last changed, including Billing or Shipping address, new payment account, or new user(s) added, in ISO 8601 format (YYYY-MM-DD).
              example: '2018-09-17'
            password_change_date:
              type: string
              description: Date the cardholder’s account with the merchant had a password change or account reset, in ISO 8601 format (YYYY-MM-DD).
              example: '2018-09-17'
            add_card_attempts:
              type: number
              description: Number of add card attempts in the last 24 hours.
              example: 1
            account_purchases:
              type: number
              description: Number of purchases with this cardholder's account during the last six months.
              example: 1
    ThirdPartySCA:
      type: object
      properties:
        cavv:
          type: string
          description: Cryptographic value indicating that authentication was successfully performed by the cardholder
          example: jELUbgG+Tgj0AREBDMLeCad+oIs=
        eci:
          type: string
          description: Electronic Commerce Indicator. The ECI is used in payer authentication to indicate the level of security used when the cardholder provided payment information to the merchant. Its value corresponds to the authentication result and the characteristics of the merchant checkout process. Each card network, e.g., Visa, MasterCard, JCB, has specific rules around the appropriate values and use of the ECI.
          example: '05'
        three_ds_version:
          type: string
          description: Indicates what version of the 3D Secure was used for authentication
          example: 2.2.0
        ds_transaction_id:
          type: string
          description: Directory Server Transaction Id. Used as an additional parameter to validate that transaction was authenticated.
          example: ac01cc2b-c1a1-4981-8c6f-400d4eec88de
        pa_res_status:
          type: string
          description: This field is included only if a PAResStatus(Payer Authentication Response Status) value is received in the authentication response.
          example: 'Y'
        ve_res_status:
          type: string
          description: |
            Set this field only if a PAResStatus(Payer Authentication Response Status) value is received in the authentication response.
            - If authentication was frictionless, use the value from AuthenticationResponse.PAResStatus.
            - If authentication was a successful challenge, set this to "C" (the directory response for challenge).
          example: C
        xid:
          type: string
          description: String used by both Visa and MasterCard which identifies a specific transaction on the Directory. This string value should remain consistent throughout a transaction's history.
          example: 47133847-13be-4ae3-9be9-e4053b9c83c0
        cavv_algorithm:
          type: string
          description: The algorithm used to generate the CAVV. Used in some scenarios for 3D Secure 1.0.
          example: '3'
        ucaf_indicator:
          type: string
          description: |
            Only received for Mastercard transactions; otherwise, this can be null.
            - 0: Non-SecureCode transaction, bypassed by the merchant
            - 1: Merchant-Only SecureCode transaction
            - 2: Fully authenticated SecureCode transaction
          example: '0'
    Error:
      type: object
      description: The overall class of error that occurred.
      properties:
        type:
          description: The error type.
          type: string
        message:
          description: A human readable message giving details about this error.
          type: string
        fields:
          type: array
          description: Details about the specific fields that had an error.
          items:
            $ref: '#/components/schemas/Field'
        errors:
          type: array
          description: An array of all the actual errors that occurred.
          items:
            $ref: '#/components/schemas/ErrorIndividual'
    ErrorIndividual:
      type: object
      description: An individual error.
      properties:
        type:
          type: string
          description: The error type.
        message:
          type: string
          description: A human readable message giving details about this error.
        fields:
          type: array
          description: Details about the specific fields that had an error.
          items:
            $ref: '#/components/schemas/Field'
    Field:
      type: object
      description: An individual field that had an error.
      properties:
        name:
          type: string
          description: The field that had an error.
        type:
          type: string
          description: The type of the field that had an error.
        value:
          type: string
          description: The value of the field that had an error.
    PaymentRegistrationResponse:
      type: object
      properties:
        payment_token:
          type: string
          example: REhZAQsABAMGQgINQVhEF0FYYDEWXANJDwIECRNVDlcTXxIOBAtXTQZXHwhdCFZpVgNqBhFGCg9UShEJUw9EFERXTl5TXURGCkcBJxEDIxMKA0VUTQkAXE06WVIQClQdAyUTAQVZAlZ5dlMgABUEJQFeGFIIBApIdlEAAhlVAiEMAAgFAwUEIAQdVFARU3MWC1NJUBtVBFYVahdXRg8FW1ZURgwJW0cGB0QCJxEEdhdTAlgGRwRQRgJ1R1cDUVBfVgIGUlQbXA5YABQHAFdXFAAGUVAVVAECAVUCAlZQUwVdRwBWQFdzRFEKF0hEABRRChELJRIBBiBiMBBXVBJRfEBWdxFRAEUCTgtUCEBmEUwRVEQKVxIFeRIAVyAXREwLXQBFIFVAVEcHUx0Ld0ABAgNYX1sNC1RnBVkITVBaEREEVh0HI0YHckYCV19dF1ELPV0HDAAWAAEdV3gdUFZ-AFdaC0cKCkZUdBEBVFIFX1gOGDkLUA8DRldURwR2R1AAeU9RC1MQBgESViJHBgRVCFkMWUcCC0cKJ0MLC0ZZCkwOFFIDUEEFDkQIXEpXCV4TC1cQVicQUVNBUQ1aV0MEABEFdhYBcRUHBQFbEFpAE09nUlpRUUFXABxWcRMHClcdAlYTAXREAVFZRgEAa1tdBVxDB1cUBHhAAVEHDgNDAVYcBHMWAgddEVpaAxARUwIWCiAcA1ANVA1RBVYFEVRRFwJxF1clEFAGVAVVFFFARxdTAhRRIxNVIRQGUAlYW1ZmAhJQBUEFeB1TBggCBVcQCwl1GkVdVVoCEQYAI0BbEENAUAIzBBwVU1NvRgMGQAMgHQYKB15HTUYGVBBWJxJUCjYBVUAXXlBGBVQUVHccVwcSRQBMAGhGSlhEDA0BUmcHXwFSRgYAFVF0RAoLYyQWAlMUAXRBVwFICUUSWF1mBltSAR0GUEYDcUYCVwEMUAVcRwFURFdwFwEKB1ZNDBBCGGdSDQZdHVFUEgdyQwZWZ2JHU1RABiZDVCFDVXMSVyYUQFlCEVhQRmxHFg4EXVpVOlEBCFcGCVYAU0BaTEdGBlYFSFtmZn1CBkwUUBZVElpZV1gHVFYBTlEJFFMFF1QGAw0TBHICARUGdlAFQ0RVE0JWVEdqRgEDV0sAXlVQZw9cDV0EAwZZBVIAGVACUgwfVQBeB0gJDwtUHgcCBgJWUFUMUglQABNwDFJbDRFBDA0CDFQKCFUKUwpS
          description: This token is used to identify and authorize the payment transaction.
        expires:
          type: string
          description: The date and time when the payment token will expire, in ISO 8601 format.
          example: '2024-08-11T19:42:21.348041724Z'
        payment_session_id:
          type: string
          description: The registered payment session ID.
          example: 76d6aaea-c1d5-11e8-a355-529269fb1459
        encoded_init_config:
          type: string
          description: A base64-encoded object containing configuration required for device fingerprinting.
          example: QSBiYXNlNjQgZW5jb2RlZCBvYmplY3Qgd2hpY2ggY29udGFpbnMgY29uZmlndXJhdGlvbiBuZWVkZWQgdG8gcGVyZm9ybSBkZXZpY2UgZmluZ2VycHJpbnRpbmcgYW5kL29yIDNEUyBNZXRob2Qu
  examples:
    payment-201-success:
      value:
        payment_token: K~OuwxbxJxAnYHJlZTBxsGB3wjGFV1fVAUIyB_fBgFUflUBF8Ddg9dIQN2Em4QUwdXDAQMBVIYAVRQCk8XBgVTH1YFUVIbVlJQHwQGBgZQAlMKIzZ2YjJ9MxsYOjJhXRVMInBiVkQVKX5IWBcVR1tdE0kPQBZxUkEVVgdaV1QKLBFJGFNcXRcibjYJdGEGUQApPlALAlYNVw9LCGs4gc8RQUEVXgwIUHA_ZgRSCVpXFF4IXlR4aCKGIkNQQglYW1YbNGQHVhBCVV1LNm5yBmMKAQgBWw86ZGBxODyKrOHwYyPk84XLZH88adme6_QydbDyj5s5RDUZNjZnDYVwNXNesUI2MgxUBAxTAbswynU==
        expires: '2025-01-31T15:17:23.749951183Z'
    invalid-input:
      value:
        type: invalid_input
        message: An invalid request was sent in, please check the nested errors for details.
        errors:
          - type: Customer-Ip.required
            message: You have not provided a valid IPv4 address
            fields:
              - name: Customer-Ip
                type: HEADER
    request-unauthenticated:
      value:
        type: request_unauthenticated
        message: Data required to authenticate your request is missing or inaccurate. Ensure that your request follows the guidelines in our documentation.
        fields:
          - name: token
            type: header
            value: jaj3982k239dka328e
    request-unauthorized:
      value:
        type: request_unauthorized
        message: Your request could not be authorized.
    upgrade-required:
      value:
        type: upgrade_required
        message: This service requires the use of TLS.
    too-many-requests:
      value:
        type: too_many_requests
        message: You have reached your capacity for this type of request.
    unknown-internal-error:
      value:
        type: unknown_internal_error
        message: An internal server error has occurred.
    service-unavailable:
      value:
        type: service_unavailable
        message: This service is currently unavailable.
