Merchants

Merchants

View and search for merchants (giving destinations) in PushPay.

Class: PushPay::Merchant Required scope: read, list_my_merchants

Setup

merchants = PushPay::Merchant.new

Methods

find(merchant_key)

Get a specific merchant by key.

merchant = merchants.find('merchant_key_here')

puts merchant['name']
puts merchant['handle']
puts merchant['status']        # "Active", "Pending", "Closed"
puts merchant['homeCountry']   # "US", "AU", "NZ", "CA"
puts merchant['key']           # Use this as merchant_key in config
puts merchant['organizationKey']

search(**params)

Search merchants by name or handle.

result = merchants.search(name: 'Bethel')

result['items'].each do |merchant|
  puts "#{merchant['name']} (#{merchant['handle']})"
end

Parameters:

Parameter	Type	Description
name	String	Search by merchant name
handle	String	Search by merchant handle
country	String	NZ, AU, CA, US
visibility	String	Visible, Hidden
status	String	Active, Pending, Closed
page	Integer	Page number (0-indexed)
pageSize	Integer	Results per page

in_scope(**params)

List all merchants your API credentials have access to. This is typically the first call you make to discover your merchant keys.

result = merchants.in_scope

result['items'].each do |merchant|
  puts "#{merchant['name']}: #{merchant['key']}"
end

near(latitude:, longitude:, country: nil, **params)

Search for merchants near a geographic location.

result = merchants.near(
  latitude: '37.7749',
  longitude: '-122.4194',
  country: 'US'
)

Merchant Response Fields

Field	Description
key	Unique merchant identifier (use as merchant_key)
name	Merchant display name
handle	URL-friendly identifier
status	Active, Pending, Closed
visibility	Visible, Hidden
homeCountry	US, AU, NZ, CA
organizationKey	Parent organization key
address	Physical address
location	Latitude/longitude
paymentParameters	Currency, limits, labels
referenceDefinitions	Custom field definitions
logo	Logo URLs for different platforms
colors	Brand colors