Core Pinch REST API covering scheduled and realtime payments, plans and subscriptions, refunds, fees, events, and health — 14 paths / 19 operations. Assembled verbatim from Pinch's published per-endpoint OpenAPI 3.1 definitions.
openapi: 3.1.0
info:
title: pinch-api
version: '2020.1'
servers:
- url: https://api.getpinch.com.au/test
security:
- sec0: []
paths:
/fees/calculate:
post:
summary: Calculate Fees
description: ''
operationId: calculate-fees
requestBody:
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Token in tkn_XXXXXXXXXXXXXXXXXXXXXX format
sourceId:
type: string
description: Source Id in src_XXXXXXXXXXXXXX format
sourceType:
type: string
amount:
type: integer
format: int64
applicationFee:
type: integer
format: int64
currency:
type: string
surcharge:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"amount\": 100,\n \"currency\": \"AUD\",\n \"netAmount\": 67,\n\
\ \"isSurcharged\": false,\n \"convertedAmount\": null,\n \"convertedCurrency\"\
: null,\n \"convertedNetAmount\": null,\n \"fees\": {\n \"transactionFee\"\
: 33,\n \"applicationFee\": 0,\n \"totalFee\": 33,\n \"currency\"\
: \"AUD\",\n \"taxRate\": 0.1,\n \"convertedTransactionFee\": null,\n\
\ \"convertedApplicationFee\": null,\n \"convertedTotalFee\": null,\n\
\ \"convertedCurrency\": null,\n \"conversionRate\": null\n },\n\
\ \"source\": {\n \"id\": null,\n \"sourceType\": \"credit-card\"\
,\n \"bankAccountNumber\": null,\n \"bankAccountBsb\": null,\n \
\ \"bankAccountName\": null,\n \"creditCardToken\": \"tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\
,\n \"cardHolderName\": \"Ben Hotdog\",\n \"expiryDate\": \"2022-12-01T00:00:00\"\
,\n \"displayCardNumber\": \"4242\",\n \"cardScheme\": \"visa\",\n \
\ \"origin\": \"AU\",\n \"funding\": \"credit\"\n },\n \"feeSchedule\"\
: {\n \"destinationZone\": \"AU\",\n \"originZone\": \"AU\",\n \
\ \"feeScheme\": \"visa-master\",\n \"percentageFee\": 0.025,\n \"\
fixedFee\": 30,\n \"cap\": 0,\n \"dishonourFee\": 0,\n \"disputeFee\"\
: 3500\n }\n}"
schema:
type: object
properties:
amount:
type: integer
example: 100
default: 0
currency:
type: string
example: AUD
netAmount:
type: integer
example: 67
default: 0
isSurcharged:
type: boolean
example: false
default: true
convertedAmount: {}
convertedCurrency: {}
convertedNetAmount: {}
fees:
type: object
properties:
transactionFee:
type: integer
example: 33
default: 0
applicationFee:
type: integer
example: 0
default: 0
totalFee:
type: integer
example: 33
default: 0
currency:
type: string
example: AUD
taxRate:
type: number
example: 0.1
default: 0
convertedTransactionFee: {}
convertedApplicationFee: {}
convertedTotalFee: {}
convertedCurrency: {}
conversionRate: {}
source:
type: object
properties:
id: {}
sourceType:
type: string
example: credit-card
bankAccountNumber: {}
bankAccountBsb: {}
bankAccountName: {}
creditCardToken:
type: string
example: tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
cardHolderName:
type: string
example: Ben Hotdog
expiryDate:
type: string
example: '2022-12-01T00:00:00'
displayCardNumber:
type: string
example: '4242'
cardScheme:
type: string
example: visa
origin:
type: string
example: AU
funding:
type: string
example: credit
feeSchedule:
type: object
properties:
destinationZone:
type: string
example: AU
originZone:
type: string
example: AU
feeScheme:
type: string
example: visa-master
percentageFee:
type: number
example: 0.025
default: 0
fixedFee:
type: integer
example: 30
default: 0
cap:
type: integer
example: 0
default: 0
dishonourFee:
type: integer
example: 0
default: 0
disputeFee:
type: integer
example: 3500
default: 0
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"You must\
\ supply one of either: Token, SourceId, SourceType\",\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: 'You must supply one of either: Token, SourceId, SourceType'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
/plans/{planId}/calculated-payments:
get:
description: ''
responses:
'200':
description: ''
parameters:
- in: path
name: planId
schema:
type: string
required: true
description: Plan Id to calculate Payments for (string identifier starting with *pln_*)
- in: query
name: startDate
schema:
type: string
format: date-time
required: true
- in: query
name: totalAmount
schema:
type: number
operationId: get_plans-planid-calculated-payments
/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
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
/refunds/nonce:
post:
summary: Check Refund Nonce
description: Check if a Nonce has already been added
operationId: check-refund-nonce
requestBody:
content:
application/json:
schema:
type: object
required:
- nonce
properties:
nonce:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Nonce Exists:
value: "{\n \"isNonceReplay\": true,\n \"nonce\": \"test1234\",\n \"data\"\
: {\n \"id\": \"ref_XGPRRXNZ\",\n \"amount\": 100,\n \"currency\"\
: \"AUD\",\n \"refundFeeCharged\": 0,\n \"requestedDate\": \"2021-05-11T02:29:56.6079210Z\"\
,\n \"submittedDate\": null,\n \"completedDate\": null,\n \"\
reasonForRefund\": \"Requested by Payer\",\n \"notes\": null,\n \"convertedAmount\"\
: null,\n \"conversionRate\": null,\n \"convertedCurrency\": null,\n\
\ \"isGross\": false,\n \"status\": \"requested\",\n \"paymentId\"\
: null,\n \"transferId\": null,\n \"refundedFees\": null,\n \"\
nonce\": \"test1234\"\n }\n}"
Nonce Doesn't Exist:
value: "{\n \"isNonceReplay\": false,\n \"nonce\": \"test12345\"\n}"
schema:
oneOf:
- title: Nonce Exists
type: object
properties:
isNonceReplay:
type: boolean
example: true
default: true
nonce:
type: string
example: test1234
data:
type: object
properties:
id:
type: string
example: ref_XGPRRXNZ
amount:
type: integer
example: 100
default: 0
currency:
type: string
example: AUD
refundFeeCharged:
type: integer
example: 0
default: 0
requestedDate:
type: string
example: '2021-05-11T02:29:56.6079210Z'
submittedDate: {}
completedDate: {}
reasonForRefund:
type: string
example: Requested by Payer
notes: {}
convertedAmount: {}
conversionRate: {}
convertedCurrency: {}
isGross:
type: boolean
example: false
default: true
status:
type: string
example: requested
paymentId: {}
transferId: {}
refundedFees: {}
nonce:
type: string
example: test1234
- title: Nonce Doesn't Exist
type: object
properties:
isNonceReplay:
type: boolean
example: false
default: true
nonce:
type: string
example: test12345
deprecated: false
/refunds:
post:
summary: Create a Refund
description: ''
operationId: create-a-refund
requestBody:
content:
application/json:
schema:
type: object
required:
- paymentId
- amount
- reason
properties:
paymentId:
type: string
description: Payment Id in pmt_XXXXXXXXXXXXXX format
amount:
type: integer
format: int32
reason:
type: string
nonce:
type: string
description: Optional. A nonce is a one-time-use reference that represents a unique
payment. Used to prevent double submissions of payments. If left empty all submissions
will be treated as unique.
examples:
Request Example:
value:
paymentId: pmt_XXXXXXXXXXXXXX
amount: 1000
reason: Requested by Payer
nonce: unique-string
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"ref_995DGQ38\",\n \"amount\": 100,\n \"currency\": \"\
AUD\",\n \"refundFeeCharged\": 0,\n \"requestedDate\": \"2021-05-14T00:08:11.7803470Z\"\
,\n \"submittedDate\": null,\n \"completedDate\": null,\n \"reasonForRefund\"\
: \"Requested by Payer\",\n \"notes\": null,\n \"convertedAmount\": null,\n\
\ \"conversionRate\": null,\n \"convertedCurrency\": null,\n \"isGross\"\
: false,\n \"status\": \"requested\",\n \"paymentId\": null,\n \"transferId\"\
: null,\n \"refundedFees\": null,\n \"nonce\": \"5781b2f0-9a09-4579-bbb8-eea734633b13\"\
\n}"
schema:
type: object
properties:
id:
type: string
example: ref_995DGQ38
amount:
type: integer
example: 100
default: 0
currency:
type: string
example: AUD
refundFeeCharged:
type: integer
example: 0
default: 0
requestedDate:
type: string
example: '2021-05-14T00:08:11.7803470Z'
submittedDate: {}
completedDate: {}
reasonForRefund:
type: string
example: Requested by Payer
notes: {}
convertedAmount: {}
conversionRate: {}
convertedCurrency: {}
isGross:
type: boolean
example: false
default: true
status:
type: string
example: requested
paymentId: {}
transferId: {}
refundedFees: {}
nonce:
type: string
example: 5781b2f0-9a09-4579-bbb8-eea734633b13
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Could\
\ not find a payment with ID: pmt_XXXXXXXXXXXXXX\",\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 payment with ID: pmt_XXXXXXXXXXXXXX'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
'403':
description: '403'
content:
application/json:
examples:
403 Nonce Replay:
value: "{\n \"isNonceReplay\": true,\n \"nonce\": \"5781b2f0-9a09-4579-bbb8-eea734633b13\"\
,\n \"data\": {\n \"id\": \"ref_995DGQ38\",\n \"amount\": 100,\n\
\ \"currency\": \"AUD\",\n \"refundFeeCharged\": 0,\n \"requestedDate\"\
: \"2021-05-14T00:08:11.7803470Z\",\n \"submittedDate\": null,\n \"\
completedDate\": null,\n \"reasonForRefund\": \"Requested by Payer\",\n \
\ \"notes\": null,\n \"convertedAmount\": null,\n \"conversionRate\"\
: null,\n \"convertedCurrency\": null,\n \"isGross\": false,\n \
\ \"status\": \"requested\",\n \"paymentId\": null,\n \"transferId\"\
: null,\n \"refundedFees\": null,\n \"nonce\": \"5781b2f0-9a09-4579-bbb8-eea734633b13\"\
\n }\n}"
schema:
type: object
properties:
isNonceReplay:
type: boolean
example: true
default: true
nonce:
type: string
example: 5781b2f0-9a09-4579-bbb8-eea734633b13
data:
type: object
properties:
id:
type: string
example: ref_995DGQ38
amount:
type: integer
example: 100
default: 0
currency:
type: string
example: AUD
refundFeeCharged:
type: integer
example: 0
default: 0
requestedDate:
type: string
example: '2021-05-14T00:08:11.7803470Z'
submittedDate: {}
completedDate: {}
reasonForRefund:
type: string
example: Requested by Payer
notes: {}
convertedAmount: {}
conversionRate: {}
convertedCurrency: {}
isGross:
type: boolean
example: false
default: true
status:
type: string
example: requested
paymentId: {}
transferId: {}
refundedFees: {}
nonce:
type: string
example: 5781b2f0-9a09-4579-bbb8-eea734633b13
deprecated: false
get:
summary: List Refunds
description: ''
operationId: list-refunds
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
- name: startDate
in: query
s
# --- truncated at 32 KB (176 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinch-payments/refs/heads/main/openapi/pinch-payments-core.yml