Pinch

The Pinch Developer Hub

Welcome to the Pinch developer hub. You'll find comprehensive guides and documentation to help you start working with Pinch as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Things to know

 

Things to know

You should include the pinch-version header in all requests. Technically it's optional, but the API could change on you and your code will just break. See Versioning.

Empty requests will break things.

If you get validation messages mentioning that you haven't supplied certain properties, but you have, the problem is almost certainly malformed json or a type mismatch. Double check your json and make sure that the data you provide matches the type of the property.

There's a test and live modes. All URLs provided here are using test. Replace this with live when moving to production.

We're keen to make this the best payments API we can. Feedback and Bug reporting is super appreciated.

Good luck!

Suggest Edits

Authentication

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://auth.getpinch.com.au/connect/token
var api = new PinchApi("mch_1Q2FdkAEv3Gqnw", "sk_3fR400N3DF6AlHESSff668j5bANVhGa9");
curl https://auth.getpinch.com.au/connect/token \
 -u mch_1Q2FdkAEv3Gqnw:sk_3fR400N3DF6AlHESSff668j5bANVhGa9 \
 -d grant_type=client_credentials \
 -d scope=api1
A binary file was returned

You couldn't be authenticated

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkRCNzgxNjc5NjYxOTE0Qjc1MzlCRTAyMEVFOUM0RjY4ODA1NzlGODYiLCJ0eXAiOiJKV1QiLCJ4NXQiOiIyM2dXZVdZWkZMZFRtLUFnN3B4UGFJQlhuNFkifQ.eyJuYmYiOjE0NjkxMDgxMjEsImV4cCI6MTQ2OTExMTcyMSwiaXNzIjoiaHR0cHM6Ly9waW5jaC1hdXRoNC5henVyZXdlYnNpdGVzLm5ldCIsImF1ZCI6Imh0dHBzOi8vcGluY2gtYXV0aDQuYXp1cmV3ZWJzaXRlcy5uZXQvcmVzb3VyY2VzIiwiY2xpZW50X2lkIjoibWNoXzFRMkZka0FFdjNHcW53IiwidGVzdF9zdWJtZXJjaGFudF9pZCI6IjEiLCJsaXZlX3N1Ym1lcmNoYW50X2lkIjoiMiIsInNjb3BlIjoiYXBpMSJ9.iArv1xKDbN-ZiDMWbH4_rUqF7KdF0PYDWm7y_aNhNDzJelHKVfF62N-OuGog6yAo0XTv2FrwABkzZG0kCuzyR_FTbxCsQz4mUO7d8AXNYNVPv4CHeGlnwIpJJwDGRrD-ufdapDsD07kXFpI11s-SX4xrqlBjjyMYI-9ghMipDZgD7CA2jX00wJSgofOKGRRiBm1-lmYo3X8sGEHP-dF7CRM1s_shrX33rMB0FHHvKooEFAbA6tA2SOEHOLVlh1C6q6zX8lGsy1AqyS0dI3avflk-A1Ez047tA472I4F73yxhPjna8ihVFNpRWasBYRBkud4jDWyPrLIsW2QTUwBIhw",
    "expires_in": 3600,
    "token_type": "Bearer"
}
{
    "error": "invalid_..."
}

Form Data

grant_type
string
required

The grant type being requested. In this case we're using our client_credentials to identify ourselves. Must be set to "client_credentials"

scope
string
required

Specifically requesting access to the api. This will probably change in future. Must be set to "api1"

 

Since our API uses Bearer Authentication you have to request a token before you can do anything else. To do this, call our authentication endpoint using basic Authentication. Your Merchant ID is the username and your Secret Key is your password.

Heads Up! Don't try to use JSON as a post body, it wont work. You need to use form-data for this one.

Suggest Edits

Get Payer

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payers/id
var payer = await api.Payer.Get(id);
curl https://api.getpinch.com.au/test/payers/{id} 
 -H "Authorization: Bearer ..."
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "pyr_d4gecz4zpa2dJb",
  "firstName": "Fred",
  "lastName": "Hamburger",
  "emailAddress": "fred@mailinator.com",
  "mobileNumber": null,
  "bsb": "123456",
  "accountNumber": "654654",
  "accountName": "Fred Hamburger",
  "agreements": [
    {
      "id": "agr_lfpojOLrVAyr4H",
      "anonymousViewToken": "9QCN9iBrIRMXcPjdE61mVf6leZduQSFFezfCaPhTp4XXcMv5I251zSvdTatjFRaa",
      "agreementDateUtc": "2017-04-18T10:01:53.0440599",
      "confirmedDateUtc": null
    }
  ]
}

Path Params

id
string
required
 

A payer is someone who you are going to debit. It stores basic information about the person and also their bank details.

Attribute
Description

id
string

The ID of the payer. Payers are always prefixed with "pyr_"

firstName
string

First Name

lastName
string

Last Name

emailAddress
string

Email Address

bsb
string

The BSB of the payer's bank account. This should be 6 digits (without dashes or spaces).

accountNumber
string

The Account Number of the payer's bank account. This should be between 3 and 11 digits long.

accountName
string

The Account Name of the payer's bank account

agreements
Array of Agreement

A list of agreements for the current Payer. An agreement represents a contract between the Payer and Pinch to allow for direct debiting of their bank account. Also known as a Direct Debit Request or DDR.

Agreement

Attribute
Description

id
string

The ID for the agreement. Prefixed with "agr_".

anonymousViewToken
string

Allows the user to access the PDF copy of the contract anonymously for a short period of time.

agreementDateUtc
date

The date that the agreement contract was generated.

confirmedDateUtc
date

The date that the user confirmed and agreed to the agreement contract.

Suggest Edits

List all payers

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payers
var payers = await api.Payer.GetPayers();
curl https://api.getpinch.com.au/test/payers 
 -H "Authorization: Bearer ..."
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "page": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalItems": 3,
  "data": [
    {
      "id": "pyr_4xdOSXNYZPCtSp",
      "firstName": "Ben",
      "lastName": "Test 7",
      "emailAddress": "bentest7@mailinator.com",
      "mobileNumber": null
    },
    {
      "id": "pyr_k9lFmPe5WZ2KxE",
      "firstName": "Ben",
      "lastName": "Test 4",
      "emailAddress": "bentest4@mailinartor.com",
      "mobileNumber": null
    },
    {
      "id": "pyr_d4gecz4zpa2dJa",
      "firstName": "Ben",
      "lastName": "Test 6",
      "emailAddress": "bentest6@mailinator.com",
      "mobileNumber": null
    }
  ]
}
 
Suggest Edits

Save a payer

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.getpinch.com.au/test/payers
// Payer with Bank Account
var resultBank = await api.Payer.Save(new PayerSaveOptions()
{
  FirstName = "Fred",
  LastName = "Hamburger",
  EmailAddress = "fred_hamburger@mailinator.com",
  MobileNumber = "0400123456",
  Source = new SourceSaveOptions()
  {
    SourceType = "bank-account",
    BankAccountName = "Fred Q Hamburger",
    BankAccountBsb = "012-001",
    BankAccountNumber = "12345678"
  }
});

var payerBank = resultBank.Data;


// Payer with Credit Card
var resultCredit = await api.Payer.Save(new PayerSaveOptions()
{
  FirstName = "Fred",
  LastName = "Hamburger",
  EmailAddress = "fred_hamburger@mailinator.com",
  MobileNumber = "0400123456",
  Source = new SourceSaveOptions()
  {
    SourceType = "credit-card",
    CreditCardToken = "tkn_n82sc5341anvmh7j98nugvdzaxdsuyte"
  }
});

var payerCredit = resultCredit.Data;
{
  "firstName": "Test",
  "lastName": "WebSample3",
  "emailAddress": "testwebsample@mailinator.com",
  "mobileNumber": "0400123456",
  "source": {
    "sourceType": "bank-account",
    "bankAccountBsb": "123456",
    "bankAccountNumber": "654654",
    "bankAccountName": "Test Websample",
  }
}

{
  "firstName": "Test",
  "lastName": "WebSample3",
  "emailAddress": "testwebsample@mailinator.com",
  "mobileNumber": "0400123456",
  "source": {
    "sourceType": "credit-card",
    "creditCardToken": "tkn_n82sc5341anvmh7j98nugvdzaxdsuyte"
  }
}
curl https://api.getpinch.com.au/test/payers 
 -H "Authorization: Bearer ..." 
 -H "Content-Type: application/json" 
 -d "{
        'firstName': 'Test', 
        'lastName': 'WebSample3',  
        'emailAddress': 'testwebsample@mailinator.com',  
        'mobileNumber': '0400123456',  
        'bsb': '123456', 
        'accountNumber': '654654', 
        'accountName': 'Test Websample',
     }"
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "pyr_ETkAferq7vtWGN",
  "firstName": "Ben",
  "lastName": "Hotdog",
  "emailAddress": "ben.hotdog@mailinator.com",
  "mobileNumber": null,
  "sources": [
    {
      "id": "src_wvegLu2lpN2E32",
      "sourceType": "credit-card",
      "bankAccountNumber": null,
      "bankAccountBsb": null,
      "bankAccountName": null,
      "creditCardToken": "tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk",
      "cardHolderName": "Ben Hotdog",
      "expiryDate": "2020-12-01T00:00:00",
      "displayCardNumber": "XXXXXXXXXXXX4242"
    },
    {
      "id": "src_hK9lmCZzQOaByv",
      "sourceType": "bank-account",
      "bankAccountNumber": "9887761",
      "bankAccountBsb": "321456",
      "bankAccountName": "Ben J Hotdog",
      "creditCardToken": null,
      "cardHolderName": null,
      "expiryDate": null,
      "displayCardNumber": null
    }
  ],
  "agreements": [
    {
      "id": "agr_IIekI5w3Ltgh00",
      "anonymousViewToken": "Gu4jtXczVjeWCyj9CIrc5mzf8BMZiaix9mXk1TNkOSx4Gw28UMrXzY4e5YlrKCR5",
      "agreementDateUtc": "2018-08-27T01:14:05.671665",
      "confirmedDateUtc": "2018-08-27T01:14:05.7765039",
      "status": "active"
    }
  ]
}
[
  {
    "propertyName": "EmailAddress",
    "errorMessage": "'Email Address' should not be empty.",
    "attemptedValue": "",
    "customState": null,
    "errorCode": "notempty_error",
    "formattedMessageArguments": [],
    "formattedMessagePlaceholderValues": {
      "PropertyName": "Email Address",
      "PropertyValue": ""
    },
    "resourceName": "notempty_error"
  }
]

Body Params

id
string

If you include an ID this endpoint will update, otherwise it create a new payer

firstName
string
required

First Name

lastName
string

Last Name

emailAddress
string
required

Email Address

mobileNumber
string

Mobile Number

 
Suggest Edits

Delete a payer

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api.getpinch.com.au/test/payers/id
var response = await api.Payer.Delete(id);
curl https://api.getpinch.com.au/test/payers/{id} \
 -H "Authorization: Bearer ..." \
 -X DELETE
A binary file was returned

Your OAuth2 token is incorrect or has expired

You will get a 200 OK without any body.

Path Params

id
string
required

The payer ID

 
Suggest Edits

Save a Payment Source

Payments sources are currently either a bank account or credit card

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.getpinch.com.au/test/payers/id/sources
// Save a Bank Account
var result = await api.Payer.SaveSource("pyr_ETkAferq7vtWGN", new SourceSaveOptions() 
{            
    SourceType = "bank-account",
    BankAccountName = "Ben Hotdog",
    BankAccountBsb = "012001",
    BankAccountNumber = "134975486",
    CreditCardToken = null
});

// Save a Credit Card
var result = await api.Payer.SaveSource("pyr_ETkAferq7vtWGN", new SourceSaveOptions() 
{            
    SourceType = "credit-card",
    BankAccountName = null,
    BankAccountBsb = null,
    BankAccountNumber = null,
    CreditCardToken = "tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk"
});
{
  "sourceType":"bank-account",
  "bankAccountName":"Ben Hotdog",
  "bankAccountBsb":"012-001",
  "bankAccountNumber":"987654321",
  "creditCardToken":null
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "id":"src_bQYJCuI13M1Sgk",
    "sourceType":"bank-account",
    "bankAccountNumber":"987654321",
    "bankAccountBsb":"012001",
    "bankAccountName":"Ben Hotdog",
    "creditCardToken":null,
    "cardHolderName":null,
    "expiryDate":null,
    "displayCardNumber":null
}

Body Params

sourceType
string

Currently either 'bank-account' or 'credit-card'

bankAccountNumber
string

The bank account number for the payer's bank account

bankAccountBsb
string

The BSB for the payer's bank account

bankAccountName
string

The name for the payer's bank account

creditCardToken
string

The credit card token created by the capture script. See the Guide for more info.

 
Suggest Edits

Get Payment

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payments/id
var payment = await api.Payment.Get(id);
curl https://api.getpinch.com.au/test/payments/{id} 
 -H "Authorization: Bearer ..."
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results

Path Params

id
string
required

The Payment ID to retrieve

 

The payment object represents a single payment, however there can be multiple attempts at trying to complete the transaction. This means that if a payment fails (aka is dishonoured) you can re-attempt it until it succeeds. This is handy for keeping track of payment attempts in one place, however you're more than welcome to create a brand new payment, instead of re-attempting a failed one.

Attribute
Description

id
string

The payment ID. Payments are prefixed with "_pmt".

payerId
string

The payer's ID

amount
integer

The payment amount in cents

transactionDate
date

The date the transaction was attempted

description
string

An optional description of the payment. This will be visible to the payer.

status
string

The current status of the payment. Will be one of:

  • scheduled - the payment is waiting to be attempted
  • processing - the payment has been sent to the bank and is now awaiting clearance (can take up to 7 days)
  • dishonoured - the payment was dishonoured by the payer's bank
  • transferred - the payment amount has successfully been transferred to you
Suggest Edits

Save scheduled payment

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.getpinch.com.au/test/payments
var result = await api.Payment.Save(new PaymentSaveOptions()
{
    PayerId = "pyr_dLCdmrOmXKwuWH",
    TransactionDate = "2017-05-05",
    Amount = 1245,
    Description = "A lovely bunch of coconuts."
});
{
	"payerId":"pyr_dLCdmrOmXKwuWH",
	"amount": 1245,
	"transactionDate": "2017-05-05",
  "description": "A lovely bunch of coconuts."
}
curl https://api.getpinch.com.au/test/payments 
 -H "Authorization: Bearer ..." 
 -H "Content-Type: application/json" 
 -d "{
	'payerId':'pyr_dLCdmrOmXKwuWH',
	'amount': 1245,
	'transactionDate': '2017-05-05',
  'description': 'A lovely bunch of coconuts.'
}"
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "pmt_E2QfgvMWTmbghy",
  "amount": 1245,
  "transactionDate": "2017-05-05T00:00:00",
  "description": "A lovely bunch of coconuts.",
  "status": "scheduled",
  "payer": {
    "id": "pyr_dLCdmrOmXKwuWH",
    "firstName": "Ben",
    "lastName": "Auto 1",
    "emailAddress": "benauto1@mailinator.cOM",
    "mobileNumber": null
  },
  "attempts": [
    {
      "amount": 1245,
      "transactionDate": "2017-05-05T00:00:00",
      "estimatedSettlementDate": null,
      "dishonour": null,
      "settlement": null,
      "status": "scheduled"
    }
  ]
}

Body Params

id
string

If you include an ID this endpoint will update, otherwise it create a new payment

payerId
string
required

The ID of the payer

amount
int32
required

The payment amount in cents

transactionDate
date
required

The date to attempt the transaction

description
string

An optional description for the payment. Will be visible to the payer.

 
Suggest Edits

Execute real-time payment

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.getpinch.com.au/test/payments/realtime
var result = await api.Payment.ExecuteRealtime(new RealtimePaymentSaveOptions()
{
    FullName = "Ben Hotdog",
    Email = "ben.hotdog@mailinator.com",
    CreditCardToken = "tkn_b78d0293rn798ydb9287e6t7f987b3",
    Amount = 1245,                
    Description = "A sweet new hat"
});
{
    "fullName": "Ben Hotdog",
    "email": "ben.hotdog@mailinator.com",
    "amount": "1245",
    "description": "A sweet new hat",
    "creditCardToken": "tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk"
}
curl https://api.getpinch.com.au/test/payments/realtime 
 -H "Authorization: Bearer ..." 
 -H "Content-Type: application/json" 
 -d "{
    'fullName': 'Ben Hotdog',
    'email': 'ben.hotdog@mailinator.com',
    'amount': 1245,
    'description': 'A sweet new hat',
    'creditCardToken': 'tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk'
}"
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "id": "pmt_oQWEenurke0QXD",
    "amount": 1245,
    "description": "A sweet new hat",
    "transactionDate": "2018-08-07T01:56:01.8675549Z",
    "status": "approved",
    "estimatedTransferDate": "2018-08-07",
    "actualTransferDate": null,
    "payer": {
        "id": "pyr_ETkAferq7vtWGN",
        "firstName": "Ben",
        "lastName": "Hotdog",
        "emailAddress": "ben.hotdog@mailinator.com",
        "mobileNumber": null
    },
    "attempts": [
        {
            "amount": 1245,
            "estimatedSettlementDate": "2018-08-07T00:00:00",
            "transactionDate": "2018-08-07T01:56:01.8675549Z",
            "source": {
                "id": "src_wvegLu2lpN2E32",
                "sourceType": "credit-card",
                "bankAccountNumber": null,
                "bankAccountBsb": null,
                "bankAccountName": null,
                "creditCardToken": "tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk",
                "cardHolderName": "Ben Hotdog",
                "expiryDate": "2020-12-01T00:00:00",
                "displayCardNumber": "XXXXXXXXXXXX4242"
            },
            "dishonour": null,
            "settlement": null,
            "status": "approved"
        }
    ]
} 

Body Params

payerId
string

The Payer ID to use, if you're executing this payment against an existing payer.

fullName
string

Use Full Name, or First Name and Last Name

firstName
string

Use Full Name, or First Name and Last Name

lastName
string

Use Full Name, or First Name and Last Name

email
string

The email address of the payer

mobileNumber
string

A non-international Australian 10-digit mobile number

amount
int32

The payment amount in cents

applicationFee
int32

Optional additional fee (in cents) that goes to the parent merchant (Managed Merchants Only)

description
string

An optional description for the payment. Will be visible to the payer.

sourceId
string

Specify an existing payment source to use for this transaction. If empty, the default will be used. If you are creating a new source, use the creditCardToken field instead.

creditCardToken
string

The credit card token created by the capture script. See the Guide for more info.

 

Failed Payments

When a payment fails, the dishonour property will contain a dishonour object. You can find more information about the failure codes here: Dishonour Codes

Suggest Edits

List scheduled payments

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payments/scheduled
var result = await api.Payment.GetScheduled();
var payments = result.Data;
curl --request GET \
  --url https://api.getpinch.com.au/test/payments/scheduled
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "page": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalItems": 1,
  "data": [
    {
      "id": "pmt_XXAY8zyvIK3FjF",
      "amount": 58397,
      "transactionDate": "2017-05-11T10:00:00",
      "description": "Randomly Generated Payment",
      "status": "scheduled",
      "payer": {
        "id": "pyr_AFPkhSyh3MSt2o",
        "firstName": "Karri",
        "lastName": "Murdough",
        "emailAddress": "Karri.Murdough66@mailinator.com",
        "mobileNumber": null
      }
    }
  ]
}

Query Params

page
int32

The current page

pageSize
int32

How many items to return for each page

 
Suggest Edits

List processed payments

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payments/processed
var result = await api.Payment.GetProcessed();
var payments = result.Data;
curl --request GET \
  --url https://api.getpinch.com.au/test/payments/processed
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "page": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalItems": 1,
  "data": [
    {
      "id": "pmt_gva4gbHmm3PTuJ",
      "amount": 1000,
      "transactionDate": "2017-05-01T00:00:00",
      "description": "8",
      "status": "settled",
      "payer": {
        "id": "pyr_dLCdmrOmXKwuWH",
        "firstName": "Ben",
        "lastName": "Auto 1",
        "emailAddress": "benauto1@mailinator.cOM",
        "mobileNumber": null
      }
    }
  ]
}

Query Params

page
int32

The current page

pageSize
int32

How many items to return for each page

 
Suggest Edits

List payments for payer

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/payments/payer/id
var payments = await api.Payment.GetForPayer(id);
curl --request GET \
  --url https://api.getpinch.com.au/test/payments/payer/id
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  {
    "id": "pmt_gva4gbHmm3PTuJ",
    "amount": 1000,
    "transactionDate": "2017-05-01T00:00:00",
    "description": "8",
    "status": "settled",
    "payer": {
      "id": "pyr_dLCdmrOmXKwuWH",
      "firstName": "Ben",
      "lastName": "Auto 1",
      "emailAddress": "benauto1@mailinator.cOM",
      "mobileNumber": null
    },
    "attempts": [
      {
        "amount": 1000,
        "transactionDate": "2017-05-01T00:00:00",
        "estimatedSettlementDate": null,
        "dishonour": null,
        "settlement": null,
        "status": "settled"
      }
    ]
  }
]

Query Params

id
string
required

The ID of the payer to fetch payments for

 
Suggest Edits

Delete payment

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api.getpinch.com.au/test/payments/id
await api.Payment.Delete(id);
A binary file was returned

Your OAuth2 token is incorrect or has expired

You will receive a 200 OK with no body

Query Params

id
string
required

The payment ID to delete

 
Suggest Edits

Get Merchant

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/merchants
var payer = await api.Merchant.Get();
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "mch_jWxu2KwXfWjO5q",
  "companyName": "BulkBuy'd",
  "contactEmail": "ben@mailinator.com",
  "abn": "18 303 842 299",
  "bsb": "123456",
  "accountNumber": "123456789",
  "accountName": "BulkBuyd",
  "streetAddress": "1 Anne St",
  "suburb": "Fortitude Valley",
  "postcode": "4001",
  "bankStatementLabel": "BULKBUY'D",
  "debitMessage": "BulkBuy'd uses direct debit to both make payments towards a bulk buy, and to receive funds if you are the organiser.",
  "createdDateUtc": "2017-04-17T13:39:58.2959561"
}
 

The merchant object represents your account. It contains details about your business including where to put your money. The more information you provide the easier it is for us to approve your account for processing real transactions.

Attribute
Description

id
string

The merchant ID. Merchants are prefixed with "mch_".

companyName
string

The name of your company.

contactEmail
string

The email address of the main contact for Pinch within your company.

accountName
date

The name of your bank account

bsb
string

The BSB for your bank account

accountNumber
string

The Account Number for your bank account

streetAddress

The Street Address for your company. A personal address is fine as well.

suburb

The suburb for your company's street address

postcode

The postcode for your company's street address

Suggest Edits

Create Managed Merchant

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api.getpinch.com.au/test/merchants/managed
var result = await api.Merchant.CreateManagedMerchant(new ManagedMerchantCreateOptions()
{
  	CompanyName = "Ben's Whitelabling",
	  CompanyEmail = "benwhitelabel@mailinator.com",
		Bsb = "012-000",
		AccountNumber = "123456",
		ContactEmail = "benwhitelabel@mailinator.com",
		ContactFirstName = "Ben",
  	ContactLastName = "Whitelabel"
});
{
	"companyName": "Ben's Whitelabling",
	"companyEmail":"benwhitelabel@mailinator.com",
	"bsb": "012-000",
	"accountNumber": "123456",
	"contactEmail": "benwhitelabel@mailinator.com",
	"contactFirstName": "Ben",
	"contactLastName": "Whitelabel"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "id": "mch_Sc6VaXIHy4dwgz",
    "companyName": "Ben's Whitelabling",
    "companyEmail": "benwhitelabel@mailinator.com",
    "companyPhone": null,
    "accountName": null,
    "bsb": "012-000",
    "accountNumber": "123456",
    "abn": null,
    "streetAddress": null,
    "suburb": null,
    "state": null,
    "postcode": null,
    "contactFirstName": "Ben",
    "contactLastName": "Whitelabel",
    "contactEmail": "benwhitelabel@mailinator.com",
    "contactPhone": null,
    "testMerchantId": "mch_test_Sc3VaXIHyudwgz",
    "testSecretKey": "sk_test_3KiN3pyg0vcIn8maFJVzbkghjC1bHRxp",
    "liveSecretKey": "sk_live_B2fjU5NFvvlK2R2KeYoTaqYToAo1BWYj",
    "testPublishableKey": "pk_test_8xHudDFK6QEp8Vo3Re6tmdOUeM4TRVEY",
    "livePublishableKey": "pk_live_XCMEK9qaSeXKlsUTWXjgZ46fjwQQIw2k"
}

Body Params

companyName
string
required

Full company name

companyEmail
string
required

Can be a general email for the company rather than a person

companyPhone
string

General phone number for the company

accountName
string

Account Name for the disbursement account

bsb
string
required

BSB for the disbursement account. Should be 6 digits excluding spaces or dashes.

accountNumber
string
required

Account Number for the disbursement account. Should be between 3 and 9 digits excluding dashes and spaces.

abn
string

ABN of the company

streetAddress
string

Primary address information

suburb
string

Primary address information

state
string

Primary address information

postcode
string

Primary address information

contactFirstName
string
required

First name of the primary contact at the company

contactLastName
string
required

Last name of the primary contact for the company

contactEmail
string
required

Direct Email Address for the primary contact of the company

contactPhone
string

Direct phone number (can be mobile) for primary contact

dob
string

Date of Birth for primary contact

governmentNumber
string

Either a Passport number or Drivers License number for the primary contact

 
Suggest Edits

Get Event

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/events/id
var event = await api.Event.Get(id);
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "evt_LzUYqjQIedZwix",
  "type": "transfer",
  "eventDate": "2017-05-07T23:30:00.2434801",
  "metadata": {
		...
  },
  "data": {
    ...
  }
}

Path Params

id
string
required

The Event ID

 

Events are generated every time something happens behind the scenes in Pinch. These will form the basis for our webhooks, though for now you need to poll for them.

Transfer Event

This event is generated whenever a new Transfer is created.

{
  "id": "evt_LzUYqjQIedZwix",
  "type": "transfer",
  "eventDate": "2017-05-07T23:30:00.2434801",
  "metadata": {
    "transferAmount": 860,
    "settlementCount": 1,
    "settlementTotal": 960,
    "dishonourCount": 0,
    "dishonourTotal": 0
  },
  "data": {
    "transfer": {
      "id": "tra_ogmLOrynWHpA1R",
      "transferDate": "2017-05-08T00:00:00",
      "amount": 860,
      "accountName": null,
      "accountNumber": null,
      "bsb": null,
      "reference": "Pinch Payments - tra_ogmLOrynWHpA1R",
      "status": "complete"
    }
  }
}

Bank Results

This event is generated each time there are payments that have been dishonoured.

{
  "id": "evt_irr1g54lyxw8lg",
  "type": "bank-results",
  "eventDate": "2017-05-08T23:30:00.0989722",
  "metadata": {
    "dishonourCount": 1,
    "dishonourAmount": 1255
  },
  "data": {
    "dishonours": [
      {
        "typeEnum": 1,
        "type": "insufficient-funds",
        "date": "2017-05-09T00:00:00",
        "fees": 500,
        "transferId": null,
        "payment": {
          "id": "pmt_qVvjwIb15cHa8Z",
          "amount": 1255,
          "transactionDate": "2017-05-08T00:00:00",
          "description": "A new set of wheels 4",
          "status": "dishonoured",
          "payer": {
            "id": "pyr_dLCdmrOmXKwuWH",
            "firstName": "Ben",
            "lastName": "Auto 1",
            "emailAddress": "benauto1@mailinator.cOM",
            "mobileNumber": "0400000123"
          }
        }
      }
    ]
  }
}
Suggest Edits

List all events

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/events
var model = await api.Event.GetEventsAll();
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "page": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalItems": 2,
  "data": [
    {
      "id": "evt_nEiBZhNJ2xNvm2",
      "type": "scheduled-process",
      "eventDate": "2017-05-28T23:30:00.1816869",
      "metadata": {
        "count": 1,
        "amount": 63022
      }
    },
    {
      "id": "evt_MnLJZUJPHgCypa",
      "type": "transfer",
      "eventDate": "2017-05-25T23:30:00.5369507",
      "metadata": {
        "transferAmount": 94651,
        "settlementCount": 1,
        "settlementTotal": 94751,
        "dishonourCount": 0,
        "dishonourTotal": 0
      }
    }
  ]
}
 
Suggest Edits

Get Transfer

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/transfers/id
var transfer = await api.Transfer.Get(id);
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "tra_AL2lekBIlafB6M",
  "transferDate": "2017-05-26T00:00:00",
  "amount": 92205,
  "accountName": "General Account",
  "accountNumber": "654654",
  "bsb": "123456",
  "reference": "Pinch Payments - tra_AL2lekBIlafB6M",
  "status": "",
  "summary": [
    {
      "name": "Settlements",
      "count": 1,
      "gross": 92805,
      "fees": 500,
      "total": 92305
    },
    {
      "name": "Dishonours",
      "count": 0,
      "gross": 0,
      "fees": 0,
      "total": 0
    },
    {
      "name": "Transfer Fee",
      "count": 1,
      "gross": 0,
      "fees": 100,
      "total": -100
    }
  ]
}

Path Params

id
string
required

The Transfer ID

 
Suggest Edits

List all transfers

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/transfers
var transfers = await api.Transfer.GetTransfers();
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  {
    "id": "tra_AL2lekBIlafB6M",
    "transferDate": "2017-05-26T00:00:00",
    "amount": 92205,
    "accountName": null,
    "accountNumber": null,
    "bsb": null,
    "reference": "Pinch Payments - tra_AL2lekBIlafB6M",
    "status": "complete"
  },
  {
    "id": "tra_Rjh4TzBRC2TZvb",
    "transferDate": "2017-05-25T00:00:00",
    "amount": 94651,
    "accountName": null,
    "accountNumber": null,
    "bsb": null,
    "reference": "Pinch Payments - tra_Rjh4TzBRC2TZvb",
    "status": "complete"
  },
  {
    "id": "tra_SbBbg8vf0yCyC9",
    "transferDate": "2017-05-24T00:00:00",
    "amount": 116312,
    "accountName": null,
    "accountNumber": null,
    "bsb": null,
    "reference": "Pinch Payments - tra_SbBbg8vf0yCyC9",
    "status": "complete"
  }
]
 
Suggest Edits

List transfer line items

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.getpinch.com.au/test/transfers/items/id
var lineItems = await api.Transfer.GetLineItemsAll(id);
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "page": 1,
  "pageSize": 50,
  "totalPages": 1,
  "totalItems": 3,
  "data": [
    {
      "id": "pmt_mfoZJr3vKSK77x",
      "type": "Settlement",
      "gross": 8898,
      "fees": 119,
      "description": "Randomly Generated Payment",
      "transactionDate": "2017-05-24T00:00:00",
      "total": 8779
    },
    {
      "id": "pmt_pGD0DcwvaBnfUz",
      "type": "Settlement",
      "gross": 50930,
      "fees": 500,
      "description": "Randomly Generated Payment",
      "transactionDate": "2017-05-24T00:00:00",
      "total": 50430
    },
    {
      "id": "pmt_LYuDfUORhYXSBW",
      "type": "Settlement",
      "gross": 57703,
      "fees": 500,
      "description": "Randomly Generated Payment",
      "transactionDate": "2017-05-24T00:00:00",
      "total": 57203
    }
  ]
}

Path Params

id
string
required

The Transfer ID