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. {...}
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. {...}
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. {...}
Valid arguments for the following parameters are:
|
||||||||||
bank_account |
The full details of the bank account where funds will be settled to. {...}
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.). {...}
|
||||||||||
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-12-11T06:57:13Z",
"updated_at": "2024-12-11T06:57:13Z",
"activated_at": null
}
}
Error Responses
401 | unauthorized |
{...}
|
---|---|---|
422 | invalid_resource |
{...}
|
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-12-11T06:57:13Z",
"created_at": "2024-06-11T06:57:13Z",
"updated_at": "2024-12-11T06:57:13Z",
"activated_at": "2024-06-14T06:57:13Z"
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
Error Responses
401 | unauthorized |
{...}
|
---|
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-12-11T06:57:13Z",
"created_at": "2024-06-11T06:57:13Z",
"updated_at": "2024-12-11T06:57:13Z",
"activated_at": "2024-06-14T06:57:13Z"
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
Error Responses
400 | invalid_search_query_param |
{...}
|
---|---|---|
401 | unauthorized |
{...}
|
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-12-11T06:57:13Z",
"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-06-11T06:57:13Z",
"updated_at": "2024-12-11T06:57:13Z",
"activated_at": "2024-06-14T06:57:13Z"
}
}
Error Responses
401 | unauthorized |
{...}
|
---|---|---|
404 | not_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 |
{...}
|
---|