openapi: 3.2.0 info: title: pinch-api Subscriptions API version: '2020.1' servers: - url: https://api.getpinch.com.au/test security: - sec0: [] tags: - name: Subscriptions paths: /subscriptions/{id}: delete: summary: Cancel Subscription description: '' operationId: cancel-subscription parameters: - name: id in: path description: Subscription Id in sub_XXXXXXXXXXXXXX format schema: type: string required: true responses: '200': description: '200' content: application/json: examples: Result: value: '[no body]' '400': description: '400' content: application/json: examples: Result: value: "{\n \"errorMessages\": [\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Could not find subscription with id: sub_XXXXXXXXXXXXXX\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n ],\n \"successful\": false\n}" schema: type: object properties: errorMessages: type: array items: type: object properties: propertyName: type: string example: '' errorMessage: type: string example: 'Could not find subscription with id: sub_XXXXXXXXXXXXXX' attemptedValue: {} customState: {} severity: type: integer example: 0 default: 0 errorCode: {} formattedMessageArguments: {} formattedMessagePlaceholderValues: {} resourceName: {} successful: type: boolean example: false default: true deprecated: false tags: - Subscriptions get: summary: Get Subscription description: '' operationId: get-subscription parameters: - name: id in: path description: Subscription Id in sub_XXXXXXXXXXXXXX format schema: type: string required: true responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"id\": \"sub_XXXXXXXXXXXXXX\",\n \"payer\": {\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Ben\",\n \"lastName\": \"Hotdog\",\n \"emailAddress\": \"ben.hotdog@mailinator.com\",\n \"mobileNumber\": null,\n \"streetAddress\": null,\n \"suburb\": null,\n \"postcode\": null,\n \"state\": null,\n \"country\": null,\n \"companyName\": null,\n \"companyRegistrationNumber\": null,\n \"metadata\": null\n },\n \"planId\": \"pln_XXXXXXXXXXXXXX\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [\n {\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"durationOffset\": 1,\n \"durationInterval\": \"months\",\n \"metadata\": \"\"\n }\n ],\n \"fixedPayments\": [\n {\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2021-05-21T14:00:00.0000000Z\"\n }\n ],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2021-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": \"\",\n \"surcharge\": [\n \"bank-account\",\n \"credit-card\"\n ]\n}" schema: type: object properties: id: type: string example: sub_XXXXXXXXXXXXXX payer: type: object properties: id: type: string example: pyr_XXXXXXXXXXXXXX firstName: type: string example: Ben lastName: type: string example: Hotdog emailAddress: type: string example: ben.hotdog@mailinator.com mobileNumber: {} streetAddress: {} suburb: {} postcode: {} state: {} country: {} companyName: {} companyRegistrationNumber: {} metadata: {} planId: type: string example: pln_XXXXXXXXXXXXXX planName: type: string example: 25% Deposit with 10% Monthly status: type: string example: active startDate: type: string example: '2021-05-21T14:00:00.0000000Z' freePeriods: type: array items: type: object properties: startDate: type: string example: '2021-05-21T14:00:00.0000000Z' durationOffset: type: integer example: 1 default: 0 durationInterval: type: string example: months metadata: type: string example: '' fixedPayments: type: array items: type: object properties: amount: type: integer example: 25000 default: 0 description: type: string example: Upfront deposit cancelPlanOnFailure: type: boolean example: true default: true metadata: {} transactionDate: type: string example: '2021-05-21T14:00:00.0000000Z' recurringPayment: type: object properties: amount: type: integer example: 10000 default: 0 endAfterNumberOfPayments: {} endAfterTotalAmount: {} frequencyInterval: type: string example: months frequencyOffset: type: integer example: 1 default: 0 description: type: string example: Monthly Repayment cancelPlanOnFailure: type: boolean example: false default: true metadata: {} endAfterDate: {} startDate: type: string example: '2021-06-21T14:00:00.0000000Z' totalAmount: type: integer example: 100000 default: 0 metadata: type: string example: '' surcharge: type: array items: type: string example: bank-account '400': description: '400' content: application/json: examples: Result: value: "[\n {\n \"propertyName\": \"SubscriptionId\",\n \"errorMessage\": \"Subscription Id sub_XXXXXXXXXXXXXX not found.\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n]" schema: type: array items: type: object properties: propertyName: type: string example: SubscriptionId errorMessage: type: string example: Subscription Id sub_XXXXXXXXXXXXXX not found. attemptedValue: {} customState: {} severity: type: integer example: 0 default: 0 errorCode: {} formattedMessageArguments: {} formattedMessagePlaceholderValues: {} resourceName: {} deprecated: false tags: - Subscriptions /subscriptions: post: summary: Create Subscription description: '' operationId: create-subscription requestBody: content: application/json: schema: type: object required: - planId - payerId properties: planId: type: string description: Plan Id in pln_XXXXXXXXXXXXXX format payerId: type: string description: Payer Id in pyr_XXXXXXXXXXXXXX format totalAmount: type: integer description: If the plan needs a total amount (percentage based plans) you must supply it here in cents. This will override the end date settings on a recurring plan to end after this total amount is paid. format: int32 startDate: type: string description: When the subscription should start. Leave blank for immediately. format: date surcharge: type: array description: If you wish to pass on the fees for certain payment methods, specify them here. Values can be "bank-account" and/or "credit-card". items: type: string sourceId: type: string description: Source Id in src_XXXXXXXXX format. If you want to use a specific Source, otherwise a Source will be automatically selected. If the Source is removed the Subscription will no longer be able to complete. examples: Request Example: value: planId: pln_ZW7iySHhEZwldh payerId: pyr_vliHRkOJIHvN6b totalAmount: 100000 startDate: '2020-05-22' surcharge: - bank-account - credit-card responses: '201': description: '201' content: application/json: examples: Result: value: "{\n \"id\": \"sub_ICbooeBtI7YE5I\",\n \"payer\": {\n \"id\": \"pyr_vliHRkOJIHvN6b\",\n \"firstName\": \"New\",\n \"lastName\": \"Payer 3\",\n \"emailAddress\": \"np3@mailinator.com\",\n \"mobileNumber\": null\n },\n \"planId\": \"pln_ZW7iySHhEZwldh\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2020-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [],\n \"fixedPayments\": [{\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2020-05-21T14:00:00.0000000Z\"\n }],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2020-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": null,\n \"surcharge\": [\"bank-account\",\"credit-card\"]\n}" schema: type: object properties: id: type: string example: sub_ICbooeBtI7YE5I payer: type: object properties: id: type: string example: pyr_vliHRkOJIHvN6b firstName: type: string example: New lastName: type: string example: Payer 3 emailAddress: type: string example: np3@mailinator.com mobileNumber: {} planId: type: string example: pln_ZW7iySHhEZwldh planName: type: string example: 25% Deposit with 10% Monthly status: type: string example: active startDate: type: string example: '2020-05-21T14:00:00.0000000Z' freePeriods: type: array fixedPayments: type: array items: type: object properties: amount: type: integer example: 25000 default: 0 description: type: string example: Upfront deposit cancelPlanOnFailure: type: boolean example: true default: true metadata: {} transactionDate: type: string example: '2020-05-21T14:00:00.0000000Z' recurringPayment: type: object properties: amount: type: integer example: 10000 default: 0 endAfterNumberOfPayments: {} endAfterTotalAmount: {} frequencyInterval: type: string example: months frequencyOffset: type: integer example: 1 default: 0 description: type: string example: Monthly Repayment cancelPlanOnFailure: type: boolean example: false default: true metadata: {} endAfterDate: {} startDate: type: string example: '2020-06-21T14:00:00.0000000Z' totalAmount: type: integer example: 100000 default: 0 metadata: {} surcharge: type: array items: type: string example: bank-account '400': description: '400' content: application/json: examples: Result: value: "[\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Could not find a plan with id: pln_XXXXXX\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n]" schema: type: array items: type: object properties: propertyName: type: string example: '' errorMessage: type: string example: 'Could not find a plan with id: pln_XXXXXX' attemptedValue: {} customState: {} severity: type: integer example: 0 default: 0 errorCode: {} formattedMessageArguments: {} formattedMessagePlaceholderValues: {} resourceName: {} deprecated: false tags: - Subscriptions get: summary: List Subscriptions description: '' operationId: list-subscriptions parameters: - name: page in: query description: The current page schema: type: integer format: int32 default: 1 - name: pageSize in: query description: How many items to return for each page. Maximum 500. schema: type: integer format: int32 default: 50 responses: '200': description: '200' content: application/json: examples: Result: value: "{\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1,\n \"data\": [\n {\n \"id\": \"sub_\",\n \"payer\": {\n \"id\": \"pyr_\",\n \"firstName\": \"Ben\",\n \"lastName\": \"Hotdog\",\n \"emailAddress\": \"ben.hotdog@mailinator.com\",\n \"mobileNumber\": null,\n \"streetAddress\": null,\n \"suburb\": null,\n \"postcode\": null,\n \"state\": null,\n \"country\": null,\n \"companyName\": null,\n \"companyRegistrationNumber\": null,\n \"metadata\": null\n },\n \"planId\": \"pln_rp0JFLx6qYaPGS\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [\n {\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"durationOffset\": 1,\n \"durationInterval\": \"months\",\n \"metadata\": \"\"\n }\n ],\n \"fixedPayments\": [\n {\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2021-05-21T14:00:00.0000000Z\"\n }\n ],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2021-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": \"\",\n \"surcharge\": [\n \"bank-account\",\n \"credit-card\"\n ]\n }\n ]\n}" schema: type: object properties: page: type: integer example: 1 default: 0 pageSize: type: integer example: 50 default: 0 totalPages: type: integer example: 1 default: 0 totalItems: type: integer example: 1 default: 0 data: type: array items: type: object properties: id: type: string example: sub_ payer: type: object properties: id: type: string example: pyr_ firstName: type: string example: Ben lastName: type: string example: Hotdog emailAddress: type: string example: ben.hotdog@mailinator.com mobileNumber: {} streetAddress: {} suburb: {} postcode: {} state: {} country: {} companyName: {} companyRegistrationNumber: {} metadata: {} planId: type: string example: pln_rp0JFLx6qYaPGS planName: type: string example: 25% Deposit with 10% Monthly status: type: string example: active startDate: type: string example: '2021-05-21T14:00:00.0000000Z' freePeriods: type: array items: type: object properties: startDate: type: string example: '2021-05-21T14:00:00.0000000Z' durationOffset: type: integer example: 1 default: 0 durationInterval: type: string example: months metadata: type: string example: '' fixedPayments: type: array items: type: object properties: amount: type: integer example: 25000 default: 0 description: type: string example: Upfront deposit cancelPlanOnFailure: type: boolean example: true default: true metadata: {} transactionDate: type: string example: '2021-05-21T14:00:00.0000000Z' recurringPayment: type: object properties: amount: type: integer example: 10000 default: 0 endAfterNumberOfPayments: {} endAfterTotalAmount: {} frequencyInterval: type: string example: months frequencyOffset: type: integer example: 1 default: 0 description: type: string example: Monthly Repayment cancelPlanOnFailure: type: boolean example: false default: true metadata: {} endAfterDate: {} startDate: type: string example: '2021-06-21T14:00:00.0000000Z' totalAmount: type: integer example: 100000 default: 0 metadata: type: string example: '' surcharge: type: array items: type: string example: bank-account deprecated: false tags: - Subscriptions components: securitySchemes: sec0: type: oauth2 flows: {} x-readme: headers: - key: pinch-version value: '2020.1' explorer-enabled: true proxy-enabled: true