socket.yml

name: paypal-subscription-payment
description: Socket for creating sunscription payments with paypal
version: 0.0.2
runtime: nodejs_v8
keywords:
  - paypal
  - subscription
endpoints:
  billing-plans:
    description: 'Create, get, list and update actions for paypal billing plan.'
    long_description: >
      This comprises of four actions for `billing-plans` resource. Make sure to
      use the request methods `POST` for creating billing plans, `PATCH` for
      updating billing plans and `GET` for showing single billing plan details
      by ID and listing billing plans that were created. Kindly refer to
      https://developer.paypal.com/docs/api/payments.billing-plans for more
      details.
    inputs:
      properties:
        create_billing_plan_details:
          type: object
          description: Detail parameters for creating a billing plan
          examples:
            - |
              {
                "description": "Create Plan for Regular",
                "type": "INFINITE"
                "merchant_preferences": {
                  "auto_bill_amount": "yes",
                  "cancel_url": "http://www.cancel.com",
                  "initial_fail_amount_action": "continue",
                  "max_fail_attempts": "1",
                  "return_url": "http://www.success.com",
                  "setup_fee": {
                      "currency": "USD",
                      "value": "25"
                  }
                },
                "name": "Testing1-Regular1",
                "payment_definitions": [
                  {
                    ....
                  }
                ]
              }
        update_billing_plan_details:
          type: array
          description: >-
            An array of JSON patch objects to apply partial updates to billing
            plan
          examples:
            - |
              [
                {
                  "op": "replace",
                  "path": "/merchant-preferences",
                  "value": {
                    "cancel_url": "https://example.com/cancel",
                    "setup_fee": {
                    "value": "5",
                    "currency": "USD"
                    }
                  }
                }
              ]
        billing_plan_id:
          type: string
          description: The ID of the billing plan to update or retrieve.
          long_description: >
            Note that this is required for get and update and shouldn't be
            passed for create or list billing plans.
          examples:
            - P-3FV74344GJ503923KW
        page:
          type: string
          description: >-
            Zero-indexed number of the first page that begins the set of pages
            that are returned (List billing plans)
        status:
          type: string
          description: >-
            Filters the plans in the response by a plan status (List billing
            plans)
          examples:
            - INACTIVE/CREATED/ACTIVE
        page_size:
          type: string
          description: Number of plans to list on a single page (List billing plans)
          examples:
            - 10
        total_required:
          type: string
          description: >-
            Indicates whether the response includes the total_items and
            total_pages fields (List billing plans)
          examples:
            - 'yes'
    outputs:
      success:
        exit_code: 200
        description: Success
        examples:
          - |
            {
              "id": "P-7DC96732KA7763723UOPKETA",
              "state": "CREATED",
              "name": "Plan with Regular and Trial Payment Definitions",
              "description": "Plan with regular and trial payment definitions.",
              "type": "FIXED",
              "payment_definitions": [ ]
              ...
            }
      fail:
        exit_code: 400
        description: Failed
        examples:
          - |
            {
              "name": "VALIDATION_ERROR",
              "details": [ ... ],
              "message": "Invalid request. See details.",
              "information_link": "https://developer.paypal.com/docs/api/payments.billing-plans#errors",
              "httpStatusCode": 400
            }
  billing-plans-activate:
    description: >-
      Endpoint that activates a billing plan so that it can be used to form
      billing agreements with users
    inputs:
      properties:
        billing_plan_id:
          type: string
          description: The ID of the billing plan.
          examples:
            - P-3FV74344GJ503923KW
    outputs:
      success:
        exit_code: 200
        description: Success
        examples:
          - 200 OK
  billing-agreements:
    description: 'Create, get, list and update actions for paypal billing agreement.'
    long_description: >
      This comprises of three actions for `billing-agreements` resource. Make
      sure to use the request methods `POST` for creating billing agreements,
      `PATCH` for updating billing agreement and `GET` for showing single
      billing agreement details by ID. Kindly refer to
      https://developer.paypal.com/docs/api/payments.billing-agreements for more
      details.
    inputs:
      properties:
        create_billing_agreement_details:
          type: object
          description: Parameters for creating a billing agreement
          examples:
            - |
              {
                "name": "Fast Speed Agreement",
                "description": "Agreement for Fast Speed Plan",
                "start_date": isoDate,
                "plan": {
                  "id": "P-0NJ10521L3680291SOAQIVTQ"
                },
                "payer": {
                  "payment_method": "paypal"
                },
                "shipping_address": {
                  "line1": "StayBr111idge Suites",
                  "line2": "Cro12ok Street",
                  "city": "San Jose",
                  "state": "CA",
                  "postal_code": "95112",
                  "country_code": "US"
                }
              }
        update_billing_agreement_details:
          type: array
          description: >-
            An array of JSON patch objects to apply partial updates to billing
            agreement
          examples:
            - |
              [
                {
                  "op": "replace",
                  "path": "/merchant-preferences",
                  "value": {
                    "description": "Newer Description",
                    "name": "New Name",
                    "shipping_address": {
                      "line1": "StayBr111idge Suites",
                      "line2": "Cro12ok Street",
                      "city": "San Jose",
                      "state": "CA",
                      "postal_code": "95112",
                      "country_code": "US"
                    }
                  }
                }
              ]
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - P-3FV74344GJ503923KW
        payment_id:
          type: string
          description: The ID of the payment to execute.
        payer_id:
          type: string
          description: The ID of the payer that PayPal passes in the return_url.
          examples:
            - 22393D847794YKER7MUI
        transactions:
          type: array
          description: >-
            An array of transaction details. For execute the transactions object
            accepts only the amount object.
          examples:
            - |
              [
                {
                  "amount": {
                    "currency": "USD",
                    "total": "1.00"
                  }
                }
              ]
  billing-agreements-bill-balance:
    description: Endpoint that bills an outstanding balance of an agreement.
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - I-1TJ3GAGG82Y9
      note:
        type: string
        description: Optional note that describes the agreement state change.
        examples:
          - Billing balance amount
      amount:
        type: object
        description: Billing agreement amounta and currency
        examples:
          - |
            {
              "value": "10",
              "currency": "USD"
            }
    outputs:
      success:
        exit_code: 204
        description: Success
        examples:
          - 204 No Content
  billing-agreements-cancel:
    description: Endpoint to cancel a billing agreement.
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - I-1TJ3GAGG82Y9
      note:
        type: string
        description: Optional note that describes the reason for the cancellation.
        examples:
          - Canceling agreement
    outputs:
      success:
        exit_code: 204
        description: Success
        examples:
          - 204 No Content
  billing-agreements-re-activate:
    description: Endpoint to re-activate a suspended billing agreement
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - P-3FV74344GJ503923KW
      note:
        type: string
        description: Optional note that describes the reason for the re-activation
        examples:
          - Re-activating agreement
    outputs:
      success:
        exit_code: 204
        description: Success
        examples:
          - 204 No Content
  billing-agreements-set-balance:
    description: Endpoint that sets the balance for an agreement
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - P-3FV74344GJ503923KW
        amount:
          type: object
          description: Billing agreement amount and currency
          examples:
            - |
              {
                "value": "100",
                "currency": "USD"
              }
    outputs:
      success:
        exit_code: 204
        description: Success
        examples:
          - 204 No Content
  billing-agreements-suspend:
    description: Endpoint that suspends a billing agreement
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - P-3FV74344GJ503923KW
      note:
        type: string
        description: Optional note that describes the reason for the state change
        examples:
          - Suspending the agreement
    outputs:
      success:
        exit_code: 204
        description: Success
        examples:
          - 204 No Content
  billing-agreements-transactions:
    description: Endpoint to list transactions for an agreement
    inputs:
      properties:
        billing_agreement_id:
          type: string
          description: The ID of a billing agreement.
          examples:
            - P-3FV74344GJ503923KW
        start_date:
          type: string
          description: The start date of the range of transactions to list
        end_date:
          type: string
          description: The end date of the range of transactions to list
    outputs:
      success:
        exit_code: 200
        description: Success
        examples:
          - |
            {
              "agreement_transaction_list": [
                {
                  "transaction_id": "I-V8SSE9WLJGY6",
                  "status": "Completed",
                  ....
                }
                ...
              ]
            }
  billing-agreements-execute:
    description: Endpoint that executes a billing agreement
    inputs:
      properties:
        payment_token:
          type: string
          description: >-
            Payment Token of format EC-XXXXXX, appended to return url as a
            parameter after buyer approves agreement
          examples:
            - EC-2V0782854X675410W
    outputs:
      success:
        exit_code: 200
        description: Success
        examples:
          - |
            {
              "id": "I-1TJ3GAGG82Y9",
              "state": "Active",
              "description": "Monthly agreement with free trial payment definition.",
              ...
            }