API Reference

Merchants API Beta

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",
  "incorporation_status": "pty_ltd",
  "registered_for_gst": true,
  "address_line_1": "58 Durham Rd",
  "address_line_2": "",
  "address_locality": "Kilsyth",
  "address_region": "VIC",
  "address_postal_code": "3137"
}

Valid arguments for the following parameters are:

incorporation_status	"sole_trader", "partnership", or "pty_ltd"

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"
}

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[incorporation_status]=pty_ltd" \
 -d "entity[registered_for_gst]=true" \
 -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 "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",
    "status": "pending_approval",
    "created_at": "2021-01-02T05:32:12Z",
    "updated_at": "2021-01-02T05:32:12Z"
  }
}

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",
      "status": "active",
      "created_at": "2020-04-17T05:43:43Z",
      "updated_at": "2020-05-26T05:48:43Z"
    }
  ],
  "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/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",
    "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,
    "last_charge_date": "2020-05-26T06:15:18Z",
    "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.75"
      },
      "domestic_currency_domestic_card_premium": {
        "fixed_fee": 30,
        "percentage_fee": "1.75"
      },
      "domestic_currency_foreign_card_core": {
        "fixed_fee": 30,
        "percentage_fee": "2.9"
      },
      "domestic_currency_foreign_card_premium": {
        "fixed_fee": 30,
        "percentage_fee": "2.9"
      },
      "foreign_currency_core": {
        "fixed_fee": 30,
        "percentage_fee": "2.9"
      },
      "foreign_currency_premium": {
        "fixed_fee": 30,
        "percentage_fee": "2.9"
      }
    },
    "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
      }
    },
    "created_at": "2020-04-17T05:43:43Z",
    "updated_at": "2020-05-26T05:48:43Z"
  }
}

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.75",
    "amex_transaction_percentage_fee": "1.75",
    "foreign_transaction_percentage_fee": "2.9",
    "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" }`