PointCheckout Customer subscription API

openapi: 3.2.0
info:
  title: Merchant Customer subscription API
  description: paymennt.com provides a collection of APIs that enable you to process and manage payments.
  version: '2.0'
servers:
- url: https://api.paymennt.com/mer/v2.0/
  description: paymennt.com live environment
- url: https://api.test.paymennt.com/mer/v2.0/
  description: paymennt.com test environment
security:
- ApiKey: []
  ApiSecret: []
tags:
- name: Customer subscription
  description: API endpoints for Customer subscription management.
paths:
  /subscription:
    get:
      tags:
      - Customer subscription
      summary: Search subscriptions
      operationId: search-subscriptions
      parameters:
      - name: status
        in: query
        description: comma separated list of subscription statuses
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - ACTIVE
            - INACTIVE
            - ARCHIVED
            - EXPIRED
      - name: customer.reference
        in: query
        description: query by customer reference Id
        required: false
        schema:
          type: string
      - name: customer.email
        in: query
        description: query by customer email
        required: false
        schema:
          type: string
      - name: customer.phone
        in: query
        description: query by customer phone number
        required: false
        schema:
          type: string
      - name: afterId
        in: query
        description: filter subscriptions after the provided id
        required: false
        schema:
          type: integer
      - name: afterTimestamp
        in: query
        description: query subscriptions created after specific date/time, date format is `yyyy-mm-dd HH:MM:SS`
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: page number, default is 0
        required: false
        schema:
          minimum: 0
          type: number
      - name: size
        in: query
        description: page size, default is 20
        required: false
        schema:
          minimum: 1
          type: number
      responses:
        '200':
          description: List of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponseSubscriptionResponseWrapper'
              exampleSetFlag: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListErrorResponse'
              exampleSetFlag: false
      x-sort:
        sort: '1130'
    post:
      tags:
      - Customer subscription
      summary: Create subscription
      operationId: create-subscription
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
            exampleSetFlag: false
        required: true
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseWrapper'
              exampleSetFlag: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionErrorResponse'
              exampleSetFlag: false
      x-sort:
        sort: '1110'
  /subscription/{subscriptionId}:
    get:
      tags:
      - Customer subscription
      summary: Get subscription by Id
      operationId: get-subscription
      parameters:
      - name: subscriptionId
        in: path
        description: Subscription Id retrieved from paymennt.com API.
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionErrorResponse'
              exampleSetFlag: false
        '200':
          description: Get subscription by ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseWrapper'
              exampleSetFlag: false
      x-sort:
        sort: '1120'
  /subscription/{subscriptionId}/pause:
    post:
      tags:
      - Customer subscription
      summary: Pause subscription
      operationId: pause-subscription
      parameters:
      - name: subscriptionId
        in: path
        description: Subscription Id retrieved from paymennt.com API.
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionErrorResponse'
              exampleSetFlag: false
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseWrapper'
              exampleSetFlag: false
      x-sort:
        sort: '1140'
  /subscription/{subscriptionId}/resume:
    post:
      tags:
      - Customer subscription
      summary: Resume subscription
      operationId: resume-subscription
      parameters:
      - name: subscriptionId
        in: path
        description: Subscription Id retrieved from paymennt.com API.
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionErrorResponse'
              exampleSetFlag: false
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseWrapper'
              exampleSetFlag: false
      x-sort:
        sort: '1150'
  /subscription/{subscriptionId}/payment:
    get:
      tags:
      - Customer subscription
      summary: Get subscription payments
      operationId: get-subscription-payments
      parameters:
      - name: subscriptionId
        in: path
        description: Subscription Id retrieved from paymennt.com API.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: page number, default is 0
        required: false
        schema:
          minimum: 0
          type: number
      - name: size
        in: query
        description: page size, default is 20
        required: false
        schema:
          minimum: 1
          type: number
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListErrorResponse'
              exampleSetFlag: false
        '200':
          description: Get subscription payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponseSubscriptionPaymentResponseWrapper'
              exampleSetFlag: false
      x-sort:
        sort: '1170'
components:
  schemas:
    SubscriptionResponseWrapper:
      type: object
      properties:
        success:
          type: boolean
          description: Whether or not this operation completed successfully.
          example: true
        elapsed:
          type: integer
          description: Time in milliseconds elapsed at server processing this request.
          format: int64
          example: 12
        result:
          $ref: '#/components/schemas/SubscriptionResponse'
    CheckoutCustomerResponse:
      type: object
      description: Customer associated with this checkout
    SubscriptionPaymentResponse:
      type: object
      properties:
        id:
          type: string
          description: Subscription payment ID at paymennt.com database
          example: '1653241101733169556'
        displayId:
          type: string
          description: Subscription payment human readable short key, serves as an easier reference to the subscription
          example: QS3IM5
        checkout:
          $ref: '#/components/schemas/CheckoutLinkResponse'
        timestamp:
          type: string
          description: The date time of creating the payment in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZZ).
          format: date-time
        cancelled:
          type: boolean
          description: Whether this payment is cancelled or not
      description: Page content array
    GetListErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether or not this operation completed successfully.
          example: false
        elapsed:
          type: integer
          description: Time in milliseconds elapsed at server processing this request.
          format: int64
          example: 3
        error:
          type: string
          description: Error message.
          example: page size parameter must be a positive integer
    PageResponseSubscriptionResponseWrapper:
      type: object
      properties:
        success:
          type: boolean
          description: Whether or not this operation completed successfully.
          example: true
        elapsed:
          type: integer
          description: Time in milliseconds elapsed at server processing this request.
          format: int64
          example: 12
        result:
          $ref: '#/components/schemas/PageResponseSubscriptionResponse'
    CheckoutLinkResponse:
      type: object
      properties:
        id:
          type: string
          description: Checkout ID at paymennt.com database
          example: '1653241101733169556'
        displayId:
          type: string
          description: Checkout human readable short key, serves as an easier reference to the checkout
          example: QS3IM5
        checkoutKey:
          type: string
          description: Checkout key, serves as a unique identifier for the checkout. Used to generate the payment payge redirect URL
          example: 90ed4298f15d46df994fd1cfbbec5aa24390e811295cf8b5
        requestId:
          type: string
          description: Merchant unique reference ID for this payment request.
          example: ORD-1234-r1
        orderId:
          type: string
          description: Merchant unique reference ID for this checkout.
          example: ORD-1234
        currency:
          type: string
          description: ISO 4217 Currency Code (3 letter currency code) associated with this checkout.
          example: USD
        amount:
          type: number
          description: The grand total of the whole order. This is the amount the customer must pay.
          example: 1499.99
        cashAmount:
          type: number
          description: Cash amount to be collected from Shopper
          example: 0.0
        status:
          type: string
          description: Current checkout status.
          example: PENDING
          enum:
          - Pending
          - Authorized
          - Paid
          - Failed
          - Cancelled
          - Expired
          - Refunded
          - Partially refunded
        totalRefunded:
          type: number
          description: The total amount refunded from the checkout in checkout currency.
          example: 0.0
        redirectUrl:
          type: string
          description: 'URL for the customer payment redirect. '
          example: https://pay.test.paymennt.com/checkout/7a3ce540effe3c9a568a577d1f717e5267e73dc503663d4f
        usedPaymentMethod:
          type: string
          description: Payment method used while processing the payment.
          example: CARD
          enum:
          - PointCheckout
          - Card
          - Cash
          - ZainCash
        customer:
          $ref: '#/components/schemas/CheckoutCustomerResponse'
        subscriptionId:
          type: string
          description: The Id of the subscription at paymennt.com database that the checkout was issued for
          example: '1619465605181100275'
        billingAddress:
          $ref: '#/components/schemas/CheckoutAddress'
        deliveryAddress:
          $ref: '#/components/schemas/CheckoutAddress'
        firebaseCollection:
          type: string
          description: Google firebase collection name, to be used to receive notifications on checkout updates.
        firebaseDatabase:
          type: string
          description: Google firebase database name, to be used to receive notifications on checkout updates.
          example: pc-test-734bc
        firebaseDocument:
          type: string
          description: Google firebase document name, to be used to receive notifications on checkout updates.
        timestamp:
          type: string
          description: The date time of creating the payment in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZZ).
          format: date-time
        branchId:
          type: string
          description: The paymennt.com branch ID associated with this checkout.
          example: '1601731695315563241'
        branchName:
          type: string
          description: The paymennt.com branch name associated with this checkout.
          example: Test store
      description: Checkout associated with the payment, this can be null if the payment link is never opened
    GetSubscriptionErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether or not this operation completed successfully.
          example: false
        elapsed:
          type: integer
          description: Time in milliseconds elapsed at server processing this request.
          format: int64
          example: 3
        error:
          type: string
          description: Error message
          example: Subscription not found for API merchant
    PageResponseSubscriptionPaymentResponseWrapper:
      type: object
      properties:
        success:
          type: boolean
          description: Whether or not this operation completed successfully.
          example: true
        elapsed:
          type: integer
          description: Time in milliseconds elapsed at server processing this request.
          format: int64
          example: 12
        result:
          $ref: '#/components/schemas/PageResponseSubscriptionPaymentResponse'
    CheckoutAddress:
      required:
      - address1
      - city
      - country
      - name
      type: object
      properties:
        name:
          type: string
          description: Address person name.
          example: '[NAME]'
        address1:
          type: string
          description: Address line 1.
          example: '[ADDRESS 1]'
        address2:
          type: string
          description: Address line 2.
          example: '[ADDRESS 2]'
        city:
          type: string
          description: Address city.
          example: '[CITY]'
        state:
          type: string
          description: Address state.
          example: '[STATE]'
        zip:
          type: string
          description: Address zip code.
          example: '12345'
        country:
          type: string
          description: Address country (ISO 3166-1 alpha-3 or alpha-2 country code)
          example: AE
      description: Delivery address
    PageResponseSubscriptionPaymentResponse:
      type: object
      properties:
        page:
          type: integer
          description: Item page number, starting with 0
          format: int32
          example: 0
        size:
          type: integer
          description: Number of items per page
          format: int32
          example: 10
        totalPages:
          type: integer
          description: Total pages
          format: int32
          example: 1
        totalElements:
          type: integer
          description: Total elements in the current page
          format: int64
          example: 7
        content:
          type: array
          description: Page content array
          items:
            $ref: '#/components/schemas/SubscriptionPaymentResponse'
      description: Result Object.
    SubscriptionRequest:
      required:
      - amount
      - currency
      - description
      - sendEvery
      - sendOnHour
      - startDate
      type: object
      properties:
        description:
          type: string
          description: Subscription decription
          example: dozen of cookies
        currency:
          type: string
          description: ISO 4217 Currency Code (3 letter currency code) associated with this subscription.
          example: USD
        amount:
          type: number
          description: The grand total of the whole order. This is the amount the customer must pay.
          example: 1499.99
        customer:
          $ref: '#/components/schemas/CheckoutCustomer'
        customerId:
          type: integer
          description: 'Customer id at paymennt.com database '
          format: int64
        startDate:
          type: string
          description: The start date of the subscription in format (yyyy-MM-dd).
          format: date
          example: 2021-08-10
        endDate:
          type: string
          description: The end date of the subscription in format (yyyy-MM-dd).
          format: date
          example: 2024-05-01
        sendOnHour:
          maximum: 23
          minimum: 0
          type: integer
          description: The hour of day in UTC the checkout will be created on
          format: int32
          example: 10
        sendEvery:
          type: string
          description: When to create the checkout
          example: TWO_MONTHS
          enum:
          - DAY
          - WEEK
          - TWO_WEEKS
          - MONTH
          - TWO_MONTHS
          - THREE_MONTHS
          - SIX_MONTHS
          - YEAR
        returnUrl:
          type: string
          description: URL to redirect user to after a successful or failed payment.(Optional)
          example: https://example.com/subscription/payment-check/
    SubscriptionResponse:
      type: object
      properties:
        id:
          type: string
          description: Subscription ID at paymennt.com database
          example: '1653241101733169556'
        displayId:
          type: string
          description: Subscription human readable short key, serves as an easier reference to the subscription
          example: QS3IM5
        description:
          type: string
          description: Subscription decription
          example: dozen of cookies
        currency:
          type: string
          description: ISO 4217 Currency Code (3 letter currency code) associated with this subscription.
          example: USD
        amount:
          type: number
          description: The grand total of the whole order. This is the amount the customer must pay.
          example: 1499.99
        status:
          type: string
          description: Current subscription status.
          example: ACTIVE
          enum:
          - ACTIVE
          - INACTIVE
          - ARCHIVED
          - EXPIRED
        customer:
          $ref: '#/components/schemas/CheckoutCustomerResponse'
        startDate:
          type: string
          description: The start date of the subscription in format (yyyy-MM-dd).
          format: date
        endDate:
          type: string
          description: The end date of the subscription in format (yyyy-MM-dd).
          format: date
        sendOnHour:
          type: integer
          description: The hour of day the checkout will be created on
          format: int32
          example: 3
        period:
          type: integer
          description: The period between every checkout to be created
          format: int32
          example: 1
        periodUnit:
          type: string
          description: The period unit
          example: DAYS
          enum:
          - DAYS
          - WEEKS
          - MONTHS
      description: Result Object.
    CheckoutCustomer:
      required:
      - email
      - firstName
      - lastName
      type: object
      properties:
        id:
          type: string
          description: Customer identifier at the merchant system.
          example: '123456'
        firstName:
          type: string
          description: Customer first name.
          example: '[First name]'
        lastName:
          type: string
          description: Customer last name.
          example: '[Last name]'
        email:
          type: string
          description: Customer email address.
          example: '[CUSTOMER EMAIL]'
        phone:
          type: string
          description: Customer phone number with international calling code (Ex. 971567xxxxxx)..
          example: '[CUSTOMER PHONE]'
      description: Customer associated with this subscription
    PageResponseSubscriptionResponse:
      type: object
      properties:
        page:
          type: integer
          description: Item page number, starting with 0
          format: int32
          example: 0
        size:
          type: integer
          description: Number of items per page
          format: int32
          example: 10
        totalPages:
          type: integer
          description: Total pages
          format: int32
          example: 1
        totalElements:
          type: integer
          description: Total elements in the current page
          format: int64
          example: 7
        content:
          type: array
          description: Page content array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
      description: Result Object.
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-PointCheckout-Api-Key
      in: header
    ApiSecret:
      type: apiKey
      name: X-PointCheckout-Api-Secret
      in: header