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.

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

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",
    "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." }`