{"openapi":"3.0.1","info":{"title":"merchants","version":"1.2.0.2345"},"servers":[{"url":"https://api.pushpay.com/"}],"paths":{"/v1/merchant/{merchantKey}/webhook/{token}":{"get":{"tags":["merchants"],"summary":"Retrieve the details for a webhook","operationId":"getMerchantWebhook","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}},{"name":"token","in":"path","description":"The textual token that uniquely identifies the webhook subscription","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/WebhookRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["manage_webhooks","merchant:manage_webhooks"]}]},"put":{"tags":["merchants"],"summary":"Update the details of the webhook","operationId":"updateMerchantWebhook","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}},{"name":"token","in":"path","description":"The textual token that uniquely identifies the webhook subscription","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/EditWebhookModel"}},"application/json":{"schema":{"$ref":"#/components/schemas/EditWebhookModel"}}},"required":true},"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/WebhookRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["manage_webhooks","merchant:manage_webhooks"]}],"x-codegen-request-body-name":"model"},"delete":{"tags":["merchants"],"summary":"Delete a webhook","description":"Deletes a webhook - any queued webhook messages will still be delivered after the webhook subscription is removed, but no new webhook messages will be queued for this webhook subscription","operationId":"deleteMerchantWebhook","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}},{"name":"token","in":"path","description":"The textual token that uniquely identifies the webhook subscription","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Request was successful","content":{}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["manage_webhooks","merchant:manage_webhooks"]}]}},"/v1/merchants/near":{"get":{"tags":["merchants"],"summary":"Search for neraby merchants","description":"Will find merchants near a geolocation (latitude and longitude).\r\n\r\nIn addition to specifying position, you can also further scope the query to a specific country via the country query parameter.\r\n\r\nValid values for country are:\r\n\r\n* US\r\n* NZ\r\n* AU\r\n* CA\r\n","operationId":"searchForNearbyMerchants","parameters":[{"name":"latitude","in":"query","description":"Latitude in degrees (valid values for earth are between -90 and +90)","schema":{"type":"number","format":"double"}},{"name":"longitude","in":"query","description":"Longitude in degrees (valid values for earth are between -180 to +180)","schema":{"type":"number","format":"double"}},{"name":"country","in":"query","description":"The country the Merchant resides within","schema":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"]}},{"name":"page","in":"query","description":"The page parameter (Note: page numbering starts at 0)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"pageSize","in":"query","description":"The page size parameter (Note: default page size is 25)","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/MerchantSearchResultsRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["read"]}]}},"/v1/merchant/{merchantKey}/webhooks":{"get":{"tags":["merchants"],"summary":"Get all webhooks registered for this merchant","operationId":"getMerchantWebhooks","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/WebhookListRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["manage_webhooks","merchant:manage_webhooks"]}]},"post":{"tags":["merchants"],"summary":"Create a new webhook","operationId":"createMerchantWebhook","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/EditWebhookModel"}},"application/json":{"schema":{"$ref":"#/components/schemas/EditWebhookModel"}}},"required":true},"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/WebhookRepresentation"}}}},"201":{"description":"Request was successful","content":{}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["manage_webhooks","merchant:manage_webhooks"]}],"x-codegen-request-body-name":"model"}},"/v1/merchant/{merchantKey}":{"get":{"tags":["merchants"],"summary":"Retrieve details of merchant","description":"Retrieves the details of the merchant including the reference definitions","operationId":"getMerchant","parameters":[{"name":"merchantKey","in":"path","description":"The unique key of the merchant - a case-sensitive series of characters","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/MerchantRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["read"]}]}},"/v1/merchants":{"get":{"tags":["merchants"],"summary":"Search for merchants","description":"You can find merchants matching one or more parameters for:\r\n\r\n* country  (Country, valid values are NZ, AU, CA or US currently).\r\n* name (Full or partial name)\r\n* handle (the full handle for a merchant)\r\n\r\nNote: Unfiltered requests will return merchants of Status = Active and Visibility = Visible\r\n\r\n","operationId":"searchMerchants","parameters":[{"name":"name","in":"query","description":"One or more terms between spaces which will each be matched partially against the name of the merchant","schema":{"type":"string"}},{"name":"handle","in":"query","description":"The unique text 'handle' assigned to the merchant","schema":{"type":"string"}},{"name":"country","in":"query","description":"The country the Merchant resides within","schema":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"]}},{"name":"visibility","in":"query","description":"Returns merchant listings based on the specified visibility filter: 'Visible' returns only visible listings, while 'Hidden' returns both visible and hidden listings","schema":{"type":"string","enum":["Hidden","Visible"]}},{"name":"status","in":"query","description":"Only include merchant listings matching the specified status - Active/Pending/Closed","schema":{"type":"string","enum":["Active","Closed","Pending"]}},{"name":"page","in":"query","description":"The page parameter (Note: page numbering starts at 0)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"pageSize","in":"query","description":"The page size parameter (Note: default page size is 25)","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/MerchantSearchResultsRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["read"]}]}},"/v1/merchants/in-scope":{"get":{"tags":["merchants"],"summary":"List in-scope Merchants","description":"You can find merchants the client's scope applies to - you can further filter this list by using one or more parameters for:\r\n\r\n* country  (Country, valid values are NZ, AU, CA or US currently).\r\n* name (Full or partial name of a merchant listing)\r\n* handle (the full handle for a merchant listing)\r\n* visibility (if the merchant listings are visible or hidden)\r\n* status (if the merchant listings are active, closed or pending)\r\n\r\nNote: Unfiltered requests will return merchants of Status = Active/Pending/Closed and Visibility = Visible/Hidden","operationId":"getInScopeMerchants","parameters":[{"name":"name","in":"query","description":"One or more terms between spaces which will each be matched partially against the name of the merchant","schema":{"type":"string"}},{"name":"handle","in":"query","description":"The unique text 'handle' assigned to the merchant","schema":{"type":"string"}},{"name":"country","in":"query","description":"The country the Merchant resides within","schema":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"]}},{"name":"visibility","in":"query","description":"Returns merchant listings based on the specified visibility filter: 'Visible' returns only visible listings, while 'Hidden' returns both visible and hidden listings","schema":{"type":"string","enum":["Hidden","Visible"]}},{"name":"status","in":"query","description":"Only include merchant listings matching the specified status - Active/Pending/Closed","schema":{"type":"string","enum":["Active","Closed","Pending"]}},{"name":"page","in":"query","description":"The page parameter (Note: page numbering starts at 0)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"pageSize","in":"query","description":"The page size parameter (Note: default page size is 25)","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"success","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/MerchantSearchResultsRepresentation"}}}},"400":{"description":"The server will not process the request due to a client error","content":{}},"401":{"description":"Request failed because the client was not authorized to perform this action","content":{}},"404":{"description":"Could not find resource","content":{}},"429":{"description":"Request was throttled due to too many requests from this client or IP address","content":{}}},"security":[{"oauth2":["read"]}]}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.pushpay.com/oauth/token","scopes":{"manage_webhooks":"Grants access to manage webhooks.","merchant:manage_webhooks":"Grants access to manage webhooks for a specific merchant.","read":"Grants read-only access."}}}}},"schemas":{"PaymentLimits":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"WebhookListRepresentation":{"required":["_links","items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WebhookRepresentation"}},"_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"EditWebhookModel":{"required":["eventTypes","target"],"type":"object","properties":{"target":{"type":"object","properties":{}},"eventTypes":{"type":"array","items":{"type":"string"}}}},"ReferenceDefinitionChoice":{"required":["isDefault","label","order","value"],"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"order":{"type":"integer"},"isDefault":{"type":"boolean"}}},"WebhookRepresentation":{"required":["_links","eventTypes","target"],"type":"object","properties":{"target":{"type":"object","properties":{}},"eventTypes":{"type":"array","items":{"type":"string"}},"_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"Colors":{"required":["primary"],"type":"object","properties":{"primary":{"type":"string"}}},"LogoInfo":{"required":["href","size"],"type":"object","properties":{"size":{"type":"integer"},"href":{"type":"string"}}},"ReferenceDefinition":{"required":["hasChoices","id","isHidden","isRequired","order","valueType"],"type":"object","properties":{"id":{"type":"integer"},"order":{"type":"integer"},"valueType":{"type":"string"},"hasChoices":{"type":"boolean"},"isHidden":{"type":"boolean"},"isRequired":{"type":"boolean"},"defaultValueType":{"type":"string"},"fieldType":{"type":"string"},"label":{"type":"string"},"placeholder":{"type":"string"},"defaultValue":{"type":"string"},"minLength":{"type":"integer"},"maxLength":{"type":"integer"},"validationRegex":{"type":"string"},"validationMessage":{"type":"string"},"validationSchema":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceDefinitionChoice"}},"key":{"type":"string"}}},"GeoLocation":{"required":["latitude","longitude"],"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}},"MerchantRepresentation":{"required":["_links","colors","homeCountry","key","location","logo","name","paymentParameters","referenceDefinitions","status","version","visibility"],"type":"object","properties":{"homeCountry":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"]},"visibility":{"type":"string","enum":["Hidden","Visible"]},"status":{"type":"string","enum":["Active","Closed","Pending"]},"version":{"type":"integer"},"key":{"type":"string"},"handle":{"type":"string"},"name":{"type":"string"},"note":{"type":"string"},"address":{"type":"string"},"location":{"$ref":"#/components/schemas/GeoLocation"},"paymentParameters":{"$ref":"#/components/schemas/PaymentParameters"},"referenceDefinitions":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceDefinition"}},"logo":{"type":"object","properties":{}},"colors":{"$ref":"#/components/schemas/Colors"},"organizationKey":{"type":"string"},"v3OrganizationKey":{"type":"string"},"_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"MerchantSearchResultsRepresentation":{"required":["_links","items","page","pageSize"],"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MerchantRepresentation"}},"_links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"Link":{"required":["href","isTemplated","rel","title"],"type":"object","properties":{"rel":{"type":"string"},"href":{"type":"string"},"title":{"type":"string"},"isTemplated":{"type":"boolean"}}},"PaymentParameters":{"required":["currency","limits","mustBePaidInSafari","payButtonLabel","paymentPlaceholder","safariPaymentUrl"],"type":"object","properties":{"currency":{"type":"string"},"payButtonLabel":{"type":"string"},"limits":{"$ref":"#/components/schemas/PaymentLimits"},"paymentPlaceholder":{"type":"string"},"mustBePaidInSafari":{"type":"boolean"},"safariPaymentUrl":{"type":"string"}}}}},"x-original-swagger-version":"2.0"}