API Reference

Merchants API

The merchants API allows you to examine merchants you have referred to us. Access requires a partner API key, which is available to approved partners. Contact us to learn about becoming a partner.

POST /merchants

Creates a new referred merchant in the system and returns a confirmation.

Parameters

contact The personal details of the user that will log in to the merchant entity account. {...} 
{
  "first_name": "Roland",
  "last_name": "Robot",
  "phone_number": "02 9876 5432",
  "email": "roland@pinpayments.com",
  "password": "new-user-password"
}
The new user will be able to reset their password here https://dashboard.pinpayments.com/reset-password
entity The legal operating details of the merchant entity. {...} 
{
  "business_registration_number": "11223491505",
  "full_legal_name": "Roland Robot's coffee robots",
  "address_line_1": "58 Durham Rd",
  "address_line_2": "",
  "address_locality": "Kilsyth",
  "address_region": "VIC",
  "address_postal_code": "3137",
  "address_country_code": "AU"
}
Address country code requires a valid ISO 3166-1 alpha-2 formatted country code for a supported country.
business The business details of the merchant entity. {...} 
{
  "trading_name": "Roland Robot's coffee robots",
  "description": "We sell robots that make coffee",
  "typical_product_price": "1000",
  "transactions_per_month": "100",
  "annual_transaction_volume": "1000000",
  "sells_physical_goods": true,
  "average_delivery_days": "14",
  "url": "https://rrcr.net.au"
}
Valid arguments for the following parameters are:
typical_product_price "20", "100", "500", "1000", or "3000"
transactions_per_month "10", "20", "100", "500", or "1000"
annual_transaction_volume "5000", "20000", "250000", or "1000000"
sells_physical_goods true, or false
average_delivery_days "1", "3", "7", "14", "30", or "40"
bank_account The full details of the bank account where funds will be settled to. {...} 
{
  "name": "RRCR",
  "bsb": "182222",
  "number": "000111111"
}
See the bank accounts API for a description of each bank account parameter.
director The details of a person legally responsible for the merchant entity (e.g. director, owner, etc.). {...} 
{
  "full_name": "Roland Robot",
  "contact_number": "02 9876 5432",
  "date_of_birth": "1984-06-12"
}
Optional notes Additional information supplied by the partner to support the merchant’s application.

Example

curl https://test-api.pinpayments.com/1/merchants -u your-secret-api-key: \
 -d "contact[first_name]=Roland" \
 -d "contact[last_name]=Robot" \
 -d "contact[phone_number]=02 9876 5432" \
 -d "contact[email]=roland@pinpayments.com" \
 -d "contact[password]=new-user-password" \
 -d "entity[business_registration_number]=11223491505" \
 -d "entity[full_legal_name]=Roland Robot's coffee robots" \
 -d "entity[address_line_1]=58 Durham Rd" \
 -d "entity[address_line_2]=" \
 -d "entity[address_locality]=Kilsyth" \
 -d "entity[address_region]=VIC" \
 -d "entity[address_postal_code]=3137" \
 -d "entity[address_country_code]=AU" \
 -d "business[trading_name]=Roland Robot's coffee robots" \
 -d "business[description]=We sell robots that make coffee" \
 -d "business[typical_product_price]=1000" \
 -d "business[transactions_per_month]=100" \
 -d "business[annual_transaction_volume]=1000000" \
 -d "business[sells_physical_goods]=true" \
 -d "business[average_delivery_days]=14" \
 -d "business[url]=https://rrcr.net.au" \
 -d "bank_account[name]=RRCR" \
 -d "bank_account[bsb]=182222" \
 -d "bank_account[number]=000111111" \
 -d "director[full_name]=Roland Robot" \
 -d "director[contact_number]=02 9876 5432" \
 -d "director[date_of_birth]=1984-06-12"
201 Created 
{
  "response": {
    "token": "mrch_gbfTHVRdvtYNDbgnrTB45",
    "email": "roland.robot@pinpayments.com",
    "business_name": "Roland Robot's Coffee Robots",
    "country_code": "AU",
    "status": "pending_approval",
    "contact_name": "Roland Robot",
    "last_charge_date": null,
    "created_at": "2024-10-13T12:40:47Z",
    "updated_at": "2024-10-13T12:40:47Z",
    "activated_at": null
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "param": "email",
      "code": "email_invalid",
      "message": "Email is not formatted properly"
    }
  ]
}

GET /merchants

Returns a paginated list of all the merchants referred by you.

Example

curl https://api.pinpayments.com/1/merchants -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "mrch_roland",
      "email": "roland@pinpayments.com",
      "business_name": "Kovacek and Sons",
      "country_code": "AU",
      "status": "active",
      "contact_name": "Roland Robot",
      "last_charge_date": "2024-10-13T12:40:47Z",
      "created_at": "2024-04-13T12:40:47Z",
      "updated_at": "2024-10-13T12:40:47Z",
      "activated_at": "2024-04-16T12:40:47Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}

GET /merchants/search

Returns a paginated list of merchants matching the search criteria.

Optional query Return only merchants whose fields match the query. Fields covered include merchant token, email, firstname, lastname or business name.
Optional start_date Return only merchants created on or after this date (e.g. 2012/12/25).
Optional end_date Return only merchants created before this date (e.g. 2013/12/25).
Optional sort The field used to sort the merchants (created_at or email or first_name or last_name or name). Default value is created_at.
Optional direction The direction in which to sort the merchants (1 for ascending or -1 for descending). Default value is 1.

Example

curl https://test-api.pinpayments.com/1/merchants/search -u your-secret-api-key: -X GET \
 -d "query=roland"
200 OK 
{
  "response": [
    {
      "token": "mrch_roland",
      "email": "roland@pinpayments.com",
      "business_name": "Kovacek and Sons",
      "country_code": "AU",
      "status": "active",
      "contact_name": "Roland Robot",
      "last_charge_date": "2024-10-13T12:40:47Z",
      "created_at": "2024-04-13T12:40:47Z",
      "updated_at": "2024-10-13T12:40:47Z",
      "activated_at": "2024-04-16T12:40:47Z"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

Error Responses

400 invalid_search_query_param {...} 
{
  "error": "invalid_search_query_param",
  "error_description": "The query parameter must be at least 3 characters in length"
}
401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}

GET /merchants/merchant-token

Returns the details of a specified merchant referred by you.

Example

curl https://api.pinpayments.com/1/merchants/merch_somestring -u your-secret-api-key:
200 OK 
{
  "response": {
    "token": "mrch_roland",
    "status": "active",
    "business_name": "Kovacek and Sons",
    "url": "https://rrcr.net.au",
    "business_registration_number": "11223491505",
    "phone": "02 9876 5432",
    "country_code": "AU",
    "contact_name": "Roland Robot",
    "contact_email": "roland@pinpayments.com",
    "skip_charge_address_validation": true,
    "send_transfer_email": true,
    "send_refund_successful_emails": true,
    "settlement_delay_days": 5,
    "amex_enabled": false,
    "maximum_charge_cents": 600000,
    "pos_maximum_charge_cents": 100000,
    "transfers_enabled": true,
    "transfers_schedule": "automatic",
    "last_charge_date": "2024-10-13T12:40:47Z",
    "test_secret_api_key": "roland_test_secret_api_key",
    "test_publishable_api_key": "roland_test_publishable_api_key",
    "api_keys": {
      "secret": "roland_secret_api_key",
      "publishable": "roland_publishable_api_key"
    },
    "pricing": {
      "domestic_currency_domestic_card_core": {
        "fixed_fee": 30,
        "percentage_fee": "1.60"
      },
      "domestic_currency_domestic_card_premium": {
        "fixed_fee": 30,
        "percentage_fee": "1.60"
      },
      "domestic_currency_foreign_card_core": {
        "fixed_fee": 30,
        "percentage_fee": "3.4"
      },
      "domestic_currency_foreign_card_premium": {
        "fixed_fee": 30,
        "percentage_fee": "3.4"
      },
      "foreign_currency_core": {
        "fixed_fee": 30,
        "percentage_fee": "3.4"
      },
      "foreign_currency_premium": {
        "fixed_fee": 30,
        "percentage_fee": "3.4"
      }
    },
    "notifications": {
      "receipts": {
        "api": true,
        "payment_page": false,
        "manual_charge": true,
        "recurring_payments": false,
        "xero_payment_page": true
      },
      "recurring_payments": {
        "subscribed": true,
        "unsubscribed": false,
        "cancelled": true,
        "renewed": false,
        "renewal_failed": true,
        "reactivated": false
      }
    },
    "bank_account": {
      "name": "Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321"
    },
    "resources": {
      "payment_page": "https://pay.pinpayments.com/roland",
      "surcharge_payment_page": "https://pay.pinpayments.com/roland/sc"
    },
    "created_at": "2024-04-13T12:40:47Z",
    "updated_at": "2024-10-13T12:40:47Z",
    "activated_at": "2024-04-16T12:40:47Z"
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /merchants/default_settings

Returns the default settings that will be applied to new merchants that have been referred by you.

Example

curl https://api.pinpayments.com/1/merchants/default_settings -u your-secret-api-key:
200 OK 
{
  "response": {
    "skip_charge_address_validation": true,
    "send_transfer_email": true,
    "send_refund_successful_emails": true,
    "settlement_delay_days": 5,
    "maximum_charge_cents": 600000,
    "pos_maximum_charge_cents": 100000,
    "transaction_fixed_fee": 30,
    "third_party_transfer_fee": 30,
    "domestic_transaction_percentage_fee": "1.60",
    "amex_transaction_percentage_fee": "1.60",
    "foreign_transaction_percentage_fee": "3.4",
    "amex": true,
    "transfer_email_line_items_attachment": false,
    "statement_descriptor_random_code": false,
    "notifications": {
      "receipts": {
        "api": true,
        "payment_page": true,
        "manual_charge": true,
        "recurring_payments": true,
        "xero_payment_page": true
      },
      "recurring_payments": {
        "subscribed": true,
        "unsubscribed": true,
        "cancelled": true,
        "renewed": true,
        "renewal_failed": true,
        "reactivated": true
      }
    }
  }
}

Error Responses

401 unauthorized {...} 
{
  "error": "unauthorized",
  "error_description": "Not authorised"
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.