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",
"status": "pending_approval",
"created_at": "2021-01-02T05:32:12Z",
"updated_at": "2021-01-02T05:32:12Z"
}
}
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",
"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 |
{...}
|
---|
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
}
},
"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": "2020-04-17T05:43:43Z",
"updated_at": "2020-05-26T05:48:43Z"
}
}
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.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 |
{...}
|
---|