Pinch Merchants API
Payfac-as-a-Service / Managed Merchants — create sub-merchant accounts under your own credentials, update merchant details, list managed merchants, and upload compliance documents; 3 paths / 4 operations.
OpenAPI Specification
openapi: 3.1.0
info:
title: pinch-api-merchants
version: '2020.1'
servers:
- url: https://api.getpinch.com.au/test
security:
- sec0: []
paths:
/merchants/managed:
post:
summary: Create Managed Merchant
description: ''
operationId: create-managed-merchant
requestBody:
content:
application/json:
schema:
type: object
required:
- companyName
- companyEmail
- bankAccountRoutingNumber
- bankAccountNumber
- contacts
- ipAddress
- userAgent
properties:
companyName:
type: string
description: Full company name
legalEntityName:
type: string
companyEmail:
type: string
description: Can be a general email for the company rather than a person
companyPhone:
type: string
description: General phone number for the company
companyWebsiteUrl:
type: string
companyRegistrationNumber:
type: string
bankAccountName:
type: string
description: Account Name for the disbursement account
bankAccountRoutingNumber:
type: string
description: BSB for the disbursement account. Should be 6 digits excluding spaces or
dashes.
bankAccountNumber:
type: string
description: Account Number for the disbursement account. Should be between 3 and 9
digits excluding dashes and spaces.
streetAddress:
type: string
description: Primary address information
suburb:
type: string
description: Primary address information
state:
type: string
description: Primary address information
postcode:
type: string
description: Primary address information
country:
type: string
bankStatementLabel:
type: string
natureOfBusiness:
type: string
organisationType:
type: string
notes:
type: string
contacts:
type: array
description: At least 1 contact is required
items:
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
contactType:
type: string
enum:
- owner
- director
- shareholder
- executive
phone:
type: string
streetAddress:
type: string
suburb:
type: string
postcode:
type: string
state:
type: string
country:
type: string
dob:
type: string
description: Recommended ISO format (yyyy-mm-dd)
format: date
isPrimaryContact:
type: boolean
required:
- email
- contactType
- isPrimaryContact
type: object
ipAddress:
type: string
description: The external IP Address of the user creating the merchant
userAgent:
type: string
description: The User Agent of the user creating the merchant
merchantIdentifiers:
type: array
description: Optional list of Identifiers for the Merchant in external providers.
items:
properties:
merchantIdentifier:
type: string
description: The external identifier of the merchant
identityProvider:
type: string
description: The external provider where this identifier is from
enum:
- fiserv
- bnz
- cybersource
type: object
reportingIdentifier:
type: string
description: Identifier to be used on Daily/Monthly reporting
timeZone:
type: string
description: Merchant timezone in tz format (See [tz list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
examples:
Request Example:
value:
companyName: Test Managed Company
legalEntityName: null
companyEmail: test.managed.company@mailinator.com
companyPhone: null
companyWebsiteUrl: null
companyRegistrationNumber: null
bankAccountRoutingNumber: '000000'
bankAccountNumber: '000000000'
bankAccountName: Test Managed Account
streetAddress: null
suburb: null
state: null
postcode: null
country: AU
bankStatementLabel: ''
natureOfBusiness: null
organisationType: ''
notes: ''
contacts:
- isPrimaryContact: false
firstName: ''
lastName: ''
email: ''
phone: null
streetAddress: null
suburb: null
postcode: null
state: null
country: null
dob: null
governmentNumberSupplied: false
contactType: ''
ownership: null
jobTitle: null
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"mch_XXXXXXX\",\n \"testMerchantId\": \"mch_test_XXXXX\"\
,\n \"testOnlyMerchant\": true,\n \"companyName\": \"Test Managed Company\"\
,\n \"legalEntityName\": null,\n \"companyEmail\": \"test.managed.company@mailinator.com\"\
,\n \"companyPhone\": null,\n \"companyWebsiteUrl\": null,\n \"companyRegistrationNumber\"\
: null,\n \"bankAccountRoutingNumber\": \"000000\",\n \"bankAccountNumber\"\
: \"000000000\",\n \"bankAccountName\": \"Test Managed Account\",\n \"streetAddress\"\
: null,\n \"suburb\": null,\n \"state\": null,\n \"postcode\": null,\n \
\ \"country\": \"AU\",\n \"bankStatementLabel\": \"\",\n \"createdDateUtc\"\
: \"2021-04-21T02:08:27.7128967Z\",\n \"natureOfBusiness\": null,\n \"organisationType\"\
: \"\",\n \"compliance\": {\n \"merchantNotes\": \"New Merchant Created\"\
,\n \"propertyErrors\": null,\n \"complianceOfficerNotes\": null,\n\
\ \"status\": \"new\",\n \"submissionDate\": \"2021-04-21T02:08:27.8146977Z\"\
,\n \"decisionDate\": null,\n \"liveEnabled\": false,\n \"transactionsEnabled\"\
: false,\n \"settlementsEnabled\": false\n },\n \"contacts\": [\n \
\ {\n \"id\": \"con_XXXXXXXXXXXXXX\",\n \"isPrimaryContact\"\
: true,\n \"firstName\": \"\",\n \"lastName\": \"\",\n \
\ \"email\": \"\",\n \"phone\": null,\n \"streetAddress\"\
: null,\n \"suburb\": null,\n \"postcode\": null,\n \
\ \"state\": null,\n \"country\": null,\n \"dob\": null,\n\
\ \"governmentNumberSupplied\": false,\n \"contactType\": \"\
owner\",\n \"ownership\": null,\n \"jobTitle\": null\n \
\ }\n ]\n}"
schema:
type: object
properties:
id:
type: string
example: mch_XXXXXXX
testMerchantId:
type: string
example: mch_test_XXXXX
testOnlyMerchant:
type: boolean
example: true
default: true
companyName:
type: string
example: Test Managed Company
legalEntityName: {}
companyEmail:
type: string
example: test.managed.company@mailinator.com
companyPhone: {}
companyWebsiteUrl: {}
companyRegistrationNumber: {}
bankAccountRoutingNumber:
type: string
example: '000000'
bankAccountNumber:
type: string
example: '000000000'
bankAccountName:
type: string
example: Test Managed Account
streetAddress: {}
suburb: {}
state: {}
postcode: {}
country:
type: string
example: AU
bankStatementLabel:
type: string
example: ''
createdDateUtc:
type: string
example: '2021-04-21T02:08:27.7128967Z'
natureOfBusiness: {}
organisationType:
type: string
example: ''
compliance:
type: object
properties:
merchantNotes:
type: string
example: New Merchant Created
propertyErrors: {}
complianceOfficerNotes: {}
status:
type: string
example: new
submissionDate:
type: string
example: '2021-04-21T02:08:27.8146977Z'
decisionDate: {}
liveEnabled:
type: boolean
example: false
default: true
transactionsEnabled:
type: boolean
example: false
default: true
settlementsEnabled:
type: boolean
example: false
default: true
contacts:
type: array
items:
type: object
properties:
id:
type: string
example: con_XXXXXXXXXXXXXX
isPrimaryContact:
type: boolean
example: true
default: true
firstName:
type: string
example: ''
lastName:
type: string
example: ''
email:
type: string
example: ''
phone: {}
streetAddress: {}
suburb: {}
postcode: {}
state: {}
country: {}
dob: {}
governmentNumberSupplied:
type: boolean
example: false
default: true
contactType:
type: string
example: owner
ownership: {}
jobTitle: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"CompanyName\",\n \"errorMessage\"\
: \"'Company Name' must not be empty.\",\n \"attemptedValue\": \"\",\n \
\ \"customState\": null,\n \"severity\": 0,\n \"errorCode\": \"NotEmptyValidator\"\
,\n \"formattedMessageArguments\": [],\n \"formattedMessagePlaceholderValues\"\
: {\n \"PropertyName\": \"Company Name\",\n \"PropertyValue\"\
: \"\"\n },\n \"resourceName\": \"NotEmptyValidator\"\n },\n {\n\
\ \"propertyName\": \"CompanyEmail\",\n \"errorMessage\": \"'Company\
\ Email' must not be empty.\",\n \"attemptedValue\": \"\",\n \"customState\"\
: null,\n \"severity\": 0,\n \"errorCode\": \"NotEmptyValidator\",\n\
\ \"formattedMessageArguments\": [],\n \"formattedMessagePlaceholderValues\"\
: {\n \"PropertyName\": \"Company Email\",\n \"PropertyValue\"\
: \"\"\n },\n \"resourceName\": \"NotEmptyValidator\"\n },\n {\n\
\ \"propertyName\": \"CompanyEmail\",\n \"errorMessage\": \"'Company\
\ Email' is not a valid email address.\",\n \"attemptedValue\": \"\",\n \
\ \"customState\": null,\n \"severity\": 0,\n \"errorCode\": \"\
EmailValidator\",\n \"formattedMessageArguments\": [],\n \"formattedMessagePlaceholderValues\"\
: {\n \"PropertyName\": \"Company Email\",\n \"PropertyValue\"\
: \"\"\n },\n \"resourceName\": \"EmailValidator\"\n },\n {\n\
\ \"propertyName\": \"BankAccountRoutingNumber\",\n \"errorMessage\"\
: \"'Bank Account Routing Number' must not be empty.\",\n \"attemptedValue\"\
: \"\",\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\"\
: \"NotEmptyValidator\",\n \"formattedMessageArguments\": [],\n \"formattedMessagePlaceholderValues\"\
: {\n \"PropertyName\": \"Bank Account Routing Number\",\n \"\
PropertyValue\": \"\"\n },\n \"resourceName\": \"NotEmptyValidator\"\
\n },\n {\n \"propertyName\": \"BankAccountNumber\",\n \"errorMessage\"\
: \"'Bank Account Number' must not be empty.\",\n \"attemptedValue\": \"\"\
,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\"\
: \"NotEmptyValidator\",\n \"formattedMessageArguments\": [],\n \"formattedMessagePlaceholderValues\"\
: {\n \"PropertyName\": \"Bank Account Number\",\n \"PropertyValue\"\
: \"\"\n },\n \"resourceName\": \"NotEmptyValidator\"\n }\n]"
schema:
type: array
items:
type: object
properties:
propertyName:
type: string
example: CompanyName
errorMessage:
type: string
example: '''Company Name'' must not be empty.'
attemptedValue:
type: string
example: ''
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode:
type: string
example: NotEmptyValidator
formattedMessageArguments:
type: array
formattedMessagePlaceholderValues:
type: object
properties:
PropertyName:
type: string
example: Company Name
PropertyValue:
type: string
example: ''
resourceName:
type: string
example: NotEmptyValidator
deprecated: false
x-readme:
code-samples:
- language: csharp
code: "var result = await api.Merchant.CreateManagedMerchant(new ManagedMerchantCreateOptions()\n\
{\n \tCompanyName = \"Ben's Whitelabling\",\n\t CompanyEmail = \"benwhitelabel@mailinator.com\"\
,\n\t\tBsb = \"012-000\",\n\t\tAccountNumber = \"123456\",\n\t\tContactEmail = \"benwhitelabel@mailinator.com\"\
,\n\t\tContactFirstName = \"Ben\",\n \tContactLastName = \"Whitelabel\"\n});"
samples-languages:
- csharp
get:
summary: List Managed Merchants
description: ''
operationId: list-managed-merchants
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "[\n {\n \"id\": \"mch_XXXXX\",\n \"testMerchantId\": \"mch_test_XXXX\"\
,\n \"testOnlyMerchant\": true,\n \"companyName\": \"Test Managed Company\"\
,\n \"legalEntityName\": null,\n \"companyEmail\": \"test.managed.company@mailinator.com\"\
,\n \"companyPhone\": null,\n \"companyWebsiteUrl\": null,\n \
\ \"companyRegistrationNumber\": null,\n \"bankAccountRoutingNumber\": \"000000\"\
,\n \"bankAccountNumber\": \"000000000\",\n \"bankAccountName\": \"\
Test Managed Account\",\n \"streetAddress\": null,\n \"suburb\": null,\n\
\ \"state\": null,\n \"postcode\": null,\n \"country\": \"AU\"\
,\n \"bankStatementLabel\": \"\",\n \"createdDateUtc\": \"2021-04-21T02:08:27.7128967\"\
,\n \"natureOfBusiness\": null,\n \"organisationType\": \"\",\n \
\ \"compliance\": {\n \"merchantNotes\": \"New Merchant Created\",\n\
\ \"propertyErrors\": null,\n \"complianceOfficerNotes\": null,\n\
\ \"status\": \"new\",\n \"submissionDate\": \"2021-04-21T02:08:27.8146977Z\"\
,\n \"decisionDate\": null,\n \"liveEnabled\": false,\n \
\ \"transactionsEnabled\": false,\n \"settlementsEnabled\": false\n\
\ },\n \"contacts\": [\n {\n \"id\": \"con_XXXXX\"\
,\n \"isPrimaryContact\": true,\n \"firstName\": \"\"\
,\n \"lastName\": \"\",\n \"email\": \"\",\n \
\ \"phone\": null,\n \"streetAddress\": null,\n \
\ \"suburb\": null,\n \"postcode\": null,\n \"state\"\
: null,\n \"country\": null,\n \"dob\": null,\n \
\ \"governmentNumberSupplied\": false,\n \"contactType\"\
: \"owner\",\n \"ownership\": null,\n \"jobTitle\":\
\ null\n }\n ]\n }\n]"
schema:
type: array
items:
type: object
properties:
id:
type: string
example: mch_XXXXX
testMerchantId:
type: string
example: mch_test_XXXX
testOnlyMerchant:
type: boolean
example: true
default: true
companyName:
type: string
example: Test Managed Company
legalEntityName: {}
companyEmail:
type: string
example: test.managed.company@mailinator.com
companyPhone: {}
companyWebsiteUrl: {}
companyRegistrationNumber: {}
bankAccountRoutingNumber:
type: string
example: '000000'
bankAccountNumber:
type: string
example: '000000000'
bankAccountName:
type: string
example: Test Managed Account
streetAddress: {}
suburb: {}
state: {}
postcode: {}
country:
type: string
example: AU
bankStatementLabel:
type: string
example: ''
createdDateUtc:
type: string
example: '2021-04-21T02:08:27.7128967'
natureOfBusiness: {}
organisationType:
type: string
example: ''
compliance:
type: object
properties:
merchantNotes:
type: string
example: New Merchant Created
propertyErrors: {}
complianceOfficerNotes: {}
status:
type: string
example: new
submissionDate:
type: string
example: '2021-04-21T02:08:27.8146977Z'
decisionDate: {}
liveEnabled:
type: boolean
example: false
default: true
transactionsEnabled:
type: boolean
example: false
default: true
settlementsEnabled:
type: boolean
example: false
default: true
contacts:
type: array
items:
type: object
properties:
id:
type: string
example: con_XXXXX
isPrimaryContact:
type: boolean
example: true
default: true
firstName:
type: string
example: ''
lastName:
type: string
example: ''
email:
type: string
example: ''
phone: {}
streetAddress: {}
suburb: {}
postcode: {}
state: {}
country: {}
dob: {}
governmentNumberSupplied:
type: boolean
example: false
default: true
contactType:
type: string
example: owner
ownership: {}
jobTitle: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
/merchants/update:
post:
summary: Update Merchant
description: ''
operationId: update-merchant
requestBody:
content:
application/json:
schema:
type: object
properties:
companyName:
type: string
legalEntityName:
type: string
companyEmail:
type: string
companyPhone:
type: string
companyWebsiteUrl:
type: string
companyRegistrationNumber:
type: string
bankAccountRoutingNumber:
type: string
bankAccountNumber:
type: string
bankAccountName:
type: string
streetAddress:
type: string
suburb:
type: string
state:
type: string
postcode:
type: string
country:
type: string
bankStatementLabel:
type: string
natureOfBusiness:
type: string
organisationType:
type: string
notes:
type: string
contacts:
type: array
items:
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
contactType:
type: string
enum:
- owner
- director
- shareholder
- executive
phone:
type: string
streetAddress:
type: string
suburb:
type: string
postcode:
type: string
state:
type: string
country:
type: string
dob:
type: string
description: Recommended ISO format (yyyy-mm-dd)
format: date
isPrimaryContact:
type: boolean
required:
- email
- contactType
- isPrimaryContact
type: object
required:
- companyName
- companyEmail
examples:
Request Example:
value:
companyName: ''
legalEntityName: null
companyEmail: ''
companyPhone: null
companyWebsiteUrl: null
companyRegistrationNumber: null
bankAccountRoutingNumber: ''
bankAccountNumber: ''
bankAccountName: ''
streetAddress: null
suburb: null
state: null
postcode: null
country: AU
bankStatementLabel: ''
natureOfBusiness: null
organisationType: ''
notes: ''
contacts:
- id: con_
isPrimaryContact: false
firstName: ''
lastName: ''
email: ''
phone: null
streetAddress: null
suburb: null
postcode: null
state: null
country: null
dob: null
governmentNumberSupplied: false
contactType: ''
ownership: null
jobTitle: null
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"mch_XXXXXX\",\n \"testMerchantId\": \"mch_test_XXXXX\",\n\
\ \"testOnlyMerchant\": false,\n \"companyName\": \"Test Merchant 123\",\n \
\ \"legalEntityName\": null,\n \"companyEmail\": \"test.merchant@mailinator.com\"\
,\n \"companyPhone\": null,\n \"companyWebsiteUrl\": null,\n \"companyRegistrationNumber\"\
: null,\n \"bankAccountRoutingNumber\": \"000000\",\n \"bankAccountNumber\"\
: \"000000000\",\n \"bankAccountName\": \"Test Bank Account\",\n \"streetAddress\"\
: null,\n \"suburb\": null,\n \"state\": null,\n \"postcode\": null,\n \
\ \"country\": \"AU\",\n \"bankStatementLabel\": \"TEST MERCHANT\",\n \"createdDateUtc\"\
: \"2021-04-14T00:30:18.226759\",\n \"logoUrl\": null,\n \"natureOfBusiness\"\
: null,\n \"organisationType\": \"\",\n \"compliance\": {\n \"merchantNotes\"\
: \"New Merchant Created\",\n \"propertyErrors\": null,\n \"complianceOfficerNotes\"\
: null,\n \"status\": \"new\",\n \"submissionDate\": \"2021-04-14T00:30:18.8283947Z\"\
,\n \"decisionDate\": null,\n \"liveEnabled\": false,\n \"transactionsEnabled\"\
: false,\n \"settlementsEnabled\": false\n },\n \"contacts\": [\n \
\ {\n \"id\": \"con_XXXXXX\",\n \"isPrimaryContact\": true,\n\
\ \"firstName\": \"Test\",\n \"lastName\": \"Contact\",\n \
\ \"email\": \"test.contact@mailinator.com\",\n \"phone\": null,\n\
\ \"streetAddress\": null,\n \"suburb\": null,\n \
\ \"postcode\": null,\n \"state\": null,\n \"country\": null,\n\
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinch-payments/refs/heads/main/openapi/pinch-payments-merchants.yml