Pinch Payers API
Manage payer records and their payment sources (bank account or credit card) plus client-side tokenisation — create/update, retrieve, list, and delete payers and payment sources; 4 paths / 6 operations.
OpenAPI Specification
openapi: 3.1.0
info:
title: pinch-api-payers
version: '2020.1'
servers:
- url: https://api.getpinch.com.au/test
security:
- sec0: []
paths:
/payers/{id}/sources:
post:
summary: Create Payment Source
description: Payments sources are currently either a bank account or credit card
operationId: create-payment-source
parameters:
- name: id
in: path
description: Payer Id in pyr_XXXXXXXXXXXXXX format
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
sourceType:
type: string
description: Currently either 'bank-account' or 'credit-card'
bankAccountNumber:
type: string
description: The bank account number for the payer's bank account
bankAccountBsb:
type: string
description: The BSB for the payer's bank account
bankAccountName:
type: string
description: The name for the payer's bank account
token:
type: string
description: The token created by the capture script (credit card or bank account token).
See the Guide for more info.
ipAddress:
type: string
examples:
Request Example:
value:
sourceType: bank-account
bankAccountName: Ben Hotdog
bankAccountBsb: 012-001
bankAccountNumber: '987654321'
creditCardToken: null
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"src_XXXXXXXXXXXXXX \",\n \"sourceType\": \"bank-account\"\
,\n \"bankAccountNumber\": \"000000000\",\n \"bankAccountBsb\": \"000000\",\n\
\ \"bankAccountName\": \"Example Name\",\n \"creditCardToken\": null,\n \"\
cardHolderName\": null,\n \"expiryDate\": null,\n \"displayCardNumber\": null,\n\
\ \"cardScheme\": null,\n \"origin\": \"AU\",\n \"funding\": null\n}\n"
schema:
type: object
properties:
id:
type: string
example: 'src_XXXXXXXXXXXXXX '
sourceType:
type: string
example: bank-account
bankAccountNumber:
type: string
example: '000000000'
bankAccountBsb:
type: string
example: '000000'
bankAccountName:
type: string
example: Example Name
creditCardToken: {}
cardHolderName: {}
expiryDate: {}
displayCardNumber: {}
cardScheme: {}
origin:
type: string
example: AU
funding: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Payer\
\ with id: pyr_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: ''
errorMessage:
type: string
example: 'Payer with id: pyr_XXXXXXXXXXXXXX not found'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
x-readme:
code-samples:
- language: csharp
code: "// Save a Bank Account\nvar result = await api.Payer.SaveSource(\"pyr_ETkAferq7vtWGN\"\
, new SourceSaveOptions() \n{ \n SourceType = \"bank-account\",\n BankAccountName\
\ = \"Ben Hotdog\",\n BankAccountBsb = \"012001\",\n BankAccountNumber = \"134975486\"\
,\n CreditCardToken = null\n});\n\n// Save a Credit Card\nvar result = await api.Payer.SaveSource(\"\
pyr_ETkAferq7vtWGN\", new SourceSaveOptions() \n{ \n SourceType = \"credit-card\"\
,\n BankAccountName = null,\n BankAccountBsb = null,\n BankAccountNumber = null,\n\
\ CreditCardToken = \"tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk\"\n});\n"
samples-languages:
- csharp
/payers/{id}:
delete:
summary: Delete Payer
description: ''
operationId: delete-payer
parameters:
- name: id
in: path
description: Payer Id in pyr_XXXXXXXXXXXXXX format
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: You will get a 200 OK without any body.
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"payerId\",\n \"errorMessage\":\
\ \"Payer with id: pyr_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: payerId
errorMessage:
type: string
example: 'Payer with id: pyr_XXXXXXXXXXXXXX not found'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
x-readme:
code-samples:
- language: csharp
code: var response = await api.Payer.Delete(id);
- language: curl
code: "curl https://api.getpinch.com.au/test/payers/{id} \\\n -H \"Authorization: Bearer ...\"\
\ \\\n -X DELETE"
samples-languages:
- csharp
- curl
get:
summary: Get Payer
description: ''
operationId: get-payer
parameters:
- name: id
in: path
description: Payer Id in pyr_XXXXXXXXXXXXX format
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Fred\",\n \"lastName\"\
: \"Hamburger\",\n \"emailAddress\": \"fred@mailinator.com\",\n \"mobileNumber\"\
: \"0400000000\",\n \"streetAddress\": \"123 Main St\",\n \"suburb\": \"Brisbane\"\
,\n \"postcode\": \"4000\",\n \"state\": \"QLD\",\n \"country\": \"Australia\"\
,\n \"companyName\": \"Fred Incorporated\",\n \"companyRegistrationNumber\": \"\
64123456789\",\n \"metadata\": null,\n \"sources\": [\n {\n \"id\": \"src_XXXXXXXXXXXXXX\"\
,\n \"sourceType\": \"bank-account\",\n \"bankAccountNumber\": \"654654\"\
,\n \"bankAccountBsb\": \"123456\",\n \"bankAccountName\": \"Fred Hamburger\"\
,\n \"token\": \"tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"cardHolderName\"\
: null,\n \"expiryDate\": null,\n \"displayCardNumber\": \"4654\",\n \
\ \"cardScheme\": null,\n \"origin\": \"AU\",\n \"funding\": null,\n \
\ \"isAuthorised\": true,\n \"supportsRealtime\": false\n }\n ],\n \"\
agreements\": [\n {\n \"id\": \"agr_XXXXXXXXXXXXXX\",\n \"anonymousViewToken\"\
: \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"agreementDateUtc\"\
: \"2017-04-18T10:01:53.0440599\",\n \"confirmedDateUtc\": null\n }\n ]\n\
}"
schema:
type: object
properties:
id:
type: string
example: pyr_XXXXXXXXXXXXXX
firstName:
type: string
example: Fred
lastName:
type: string
example: Hamburger
emailAddress:
type: string
example: fred@mailinator.com
mobileNumber:
type: string
example: '0400000000'
streetAddress:
type: string
example: 123 Main St
suburb:
type: string
example: Brisbane
postcode:
type: string
example: '4000'
state:
type: string
example: QLD
country:
type: string
example: Australia
companyName:
type: string
example: Fred Incorporated
companyRegistrationNumber:
type: string
example: '64123456789'
metadata: {}
sources:
type: array
items:
type: object
properties:
id:
type: string
example: src_XXXXXXXXXXXXXX
sourceType:
type: string
example: bank-account
bankAccountNumber:
type: string
example: '654654'
bankAccountBsb:
type: string
example: '123456'
bankAccountName:
type: string
example: Fred Hamburger
token:
type: string
example: tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
cardHolderName: {}
expiryDate: {}
displayCardNumber:
type: string
example: '4654'
cardScheme: {}
origin:
type: string
example: AU
funding: {}
isAuthorised:
type: boolean
example: true
default: true
supportsRealtime:
type: boolean
example: false
default: true
agreements:
type: array
items:
type: object
properties:
id:
type: string
example: agr_XXXXXXXXXXXXXX
anonymousViewToken:
type: string
example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
agreementDateUtc:
type: string
example: '2017-04-18T10:01:53.0440599'
confirmedDateUtc: {}
'404':
description: '404'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-readme:
code-samples:
- language: csharp
code: var payer = await api.Payer.Get(id);
samples-languages:
- csharp
/payers/{id}/sources/{sourceId}:
delete:
summary: Delete Payment Source
description: ''
operationId: delete-payment-source
parameters:
- name: id
in: path
description: Payer Id in pyr_XXXXXXXXXXXXXX format
required: true
schema:
type: string
- name: sourceId
in: path
description: Source Id in src_XXXXXXXXXXXXXX format
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: You will get a 200 OK without any body.
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"sourceId\",\n \"errorMessage\"\
: \"Source with id: src_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: sourceId
errorMessage:
type: string
example: 'Source with id: src_XXXXXXXXXXXXXX not found'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
x-readme:
code-samples:
- language: csharp
code: var response = await api.Payer.DeleteSource(id);
- language: curl
code: "curl https://api.getpinch.com.au/test/payers/{id}/sources/{sourceid} \\\n -H \"Authorization:\
\ Bearer ...\" \\\n -X DELETE"
samples-languages:
- csharp
- curl
/payers:
get:
summary: List Payers
description: ''
operationId: list-payers
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: filter
in: query
description: Optional string filter to search for payers by Name or Email address
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\"\
: 3,\n \"data\": [\n {\n \"id\": \"pyr_4xdOSXNYZPCtSp\",\n \"firstName\"\
: \"Ben\",\n \"lastName\": \"Test 7\",\n \"emailAddress\": \"bentest7@mailinator.com\"\
,\n \"mobileNumber\": null\n },\n {\n \"id\": \"pyr_k9lFmPe5WZ2KxE\"\
,\n \"firstName\": \"Ben\",\n \"lastName\": \"Test 4\",\n \"emailAddress\"\
: \"bentest4@mailinator.com\",\n \"mobileNumber\": null\n },\n {\n \
\ \"id\": \"pyr_d4gecz4zpa2dJa\",\n \"firstName\": \"Ben\",\n \"lastName\"\
: \"Test 6\",\n \"emailAddress\": \"bentest6@mailinator.com\",\n \"mobileNumber\"\
: null\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: 3
default: 0
data:
type: array
items:
type: object
properties:
id:
type: string
example: pyr_4xdOSXNYZPCtSp
firstName:
type: string
example: Ben
lastName:
type: string
example: Test 7
emailAddress:
type: string
example: bentest7@mailinator.com
mobileNumber: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-readme:
code-samples:
- language: csharp
code: var payers = await api.Payer.GetPayers();
- language: curl
code: "curl https://api.getpinch.com.au/test/payers \n -H \"Authorization: Bearer ...\""
samples-languages:
- csharp
- curl
post:
summary: Create or Update Payer
description: ''
operationId: save-payer
requestBody:
content:
application/json:
schema:
type: object
required:
- firstName
- emailAddress
properties:
id:
type: string
description: If you include an ID this endpoint will update, otherwise it create a new
payer
fullName:
type: string
firstName:
type: string
description: First Name
lastName:
type: string
description: Last Name
emailAddress:
type: string
description: Email Address
mobileNumber:
type: string
description: Mobile Number
source:
type: object
description: Optionally add a payment source along with the Payer
required:
- sourceType
- token
properties:
sourceType:
type: string
description: Currently either 'bank-account' or 'credit-card'
enum:
- bank-account
- credit-card
token:
type: string
description: The credit card token created by the capture script. See the Guide
for more info.
ipAddress:
type: string
companyName:
type: string
companyRegistrationNumber:
type: string
streetAddress:
type: string
suburb:
type: string
state:
type: string
postcode:
type: string
country:
type: string
metadata:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Test\",\n \"\
lastName\": \"WebSample3\",\n \"emailAddress\": \"testwebsample@mailinator.com\"\
,\n \"mobileNumber\": \"0400000000\",\n \"streetAddress\": \"123 Fake st\",\n\
\ \"suburb\": \"Teneriffe\",\n \"postcode\": \"4005\",\n \"state\": \"QLD\"\
,\n \"country\": \"Australia\",\n \"companyName\": \"Test Company\",\n \"\
companyRegistrationNumber\": \"111111\",\n \"metadata\": null,\n \"sources\"\
: [\n {\n \"id\": \"src_XXXXXXXXXXXXXX\",\n \"sourceType\"\
: \"credit-card\",\n \"bankAccountNumber\": null,\n \"bankAccountBsb\"\
: null,\n \"bankAccountName\": null,\n \"creditCardToken\":\
\ \"tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\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 {\n \"id\"\
: \"src_XXXXXXXXXXXXXX\",\n \"sourceType\": \"bank-account\",\n \
\ \"bankAccountNumber\": \"000000000\",\n \"bankAccountBsb\": \"000000\"\
,\n \"bankAccountName\": \"Example Name\",\n \"creditCardToken\"\
: null,\n \"cardHolderName\": null,\n \"expiryDate\": null,\n\
\ \"displayCardNumber\": null,\n \"cardScheme\": null,\n \
\ \"origin\": \"AU\",\n \"funding\": null\n }\n ],\n\
\ \"agreements\": [\n {\n \"id\": \"agr_XXXXXXXXXXXXXX\",\n \
\ \"anonymousViewToken\": \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\
,\n \"agreementDateUtc\": \"2021-04-29T05:30:44.0094217Z\",\n \
\ \"confirmedDateUtc\": \"2021-04-29T05:30:44.076392Z\",\n \"status\"\
: \"active\"\n }\n ]\n}"
schema:
type: object
properties:
id:
type: string
example: pyr_XXXXXXXXXXXXXX
firstName:
type: string
example: Test
lastName:
type: string
example: WebSample3
emailAddress:
type: string
example: testwebsample@mailinator.com
mobileNumber:
type: string
example: '0400000000'
streetAddress:
type: string
example: 123 Fake st
suburb:
type: string
example: Teneriffe
postcode:
type: string
example: '4005'
state:
type: string
example: QLD
country:
type: string
example: Australia
companyName:
type: string
example: Test Company
companyRegistrationNumber:
type: string
example: '111111'
metadata: {}
sources:
type: array
items:
type: object
properties:
id:
type: string
example: src_XXXXXXXXXXXXXX
sourceType:
type: string
example: credit-card
bankAccountNumber: {}
bankAccountBsb: {}
bankAccountName: {}
creditCardToken:
type: string
example: tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
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
agreements:
type: array
items:
type: object
properties:
id:
type: string
example: agr_XXXXXXXXXXXXXX
anonymousViewToken:
type: string
example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
agreementDateUtc:
type: string
example: '2021-04-29T05:30:44.0094217Z'
confirmedDateUtc:
type: string
example: '2021-04-29T05:30:44.076392Z'
status:
type: string
example: active
'201':
description: '201'
content:
text/plain:
examples:
Result:
value: "{\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Test\",\n \"\
lastName\": \"WebSample3\",\n \"emailAddress\": \"testwebsample@mailinator.com\"\
,\n \"mobileNumber\": \"0400000000\",\n \"streetAddress\": \"123 Fake st\",\n\
\ \"suburb\": \"Teneriffe\",\n \"postcode\": \"4005\",\n \"state\": \"QLD\"\
,\n \"country\": \"Australia\",\n \"companyName\": \"Test Company\",\n \"\
companyRegistrationNumber\": \"112233\",\n \"metadata\": null,\n \"sources\"\
: [\n {\n \"id\": \"src_XXXXXXXXXXXXXX\",\n \"sourceType\"\
: \"bank-account\",\n \"bankAccountNumber\": \"000000000\",\n \
\ \"bankAccountBsb\": \"000000\",\n \"bankAccountName\": \"Example Name\"\
,\n \"creditCardToken\": null,\n \"cardHolderName\": null,\n\
\ \"expiryDate\": null,\n \"displayCardNumber\": null,\n \
\ \"cardScheme\": null,\n \"origin\": \"AU\"\n }\n ],\n\
\ \"agreements\": [\n {\n \"id\": \"agr_XXXXXXXXXXXXXX\",\n \
\ \"anonymousViewToken\": \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \
\ \"agreementDateUtc\": \"2021-04-16T04:28:04.2957723Z\",\n \"\
confirmedDateUtc\": \"2021-04-16T04:28:04.3152653Z\",\n \"status\": \"\
active\"\n }\n ]\n}"
schema:
type: object
properties:
id:
type: string
example: pyr_XXXXXXXXXXXXXX
firstName:
type: string
example: Test
lastName:
type: string
example: WebSample3
emailAddress:
type: string
example: testwebsample@mailinator.com
mobileNumber:
type: string
example: '0400000000'
streetAddress:
type: string
example: 123 Fake st
suburb:
type: string
example: Teneriffe
postcode:
type: string
example: '4005'
state:
type: string
example: QLD
country:
type: string
example: Australia
companyName:
type: string
example: Test Company
companyRegistrationNumber:
type: string
example: '112233'
metadata: {}
sources:
type: array
items:
type: object
properties:
id:
type: string
example: src_XXXXXXXXXXXXXX
sourceType:
type: string
example: bank-account
bankAccountNumber:
type: string
example: '000000000'
bankAccountBsb:
type: string
example: '000000'
bankAccountName:
type: string
example: Example Name
creditCardToken: {}
cardHolderName: {}
expiryDate: {}
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinch-payments/refs/heads/main/openapi/pinch-payments-payers.yml