PayU Partner-Merchant-Registration API
Below are the endpoints that enable you to create the necessary entities (Firm, Url, Shop, POS) for your partner.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/payu:payu-partner-merchant-registration-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
version: 2.1.0
title: PayU GPO Europe REST Partner Merchant Registration API
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
x-logo:
url: https://poland.payu.com/wp-content/themes/global-website/assets/src/images/payu-logo.svg
description: '# Overview
This reference is designed to assist you in effectively utilizing the PayU REST API to enhance your online payment capabilities.'
servers:
- url: https://secure.payu.com
description: Production Server
- url: https://secure.snd.payu.com
description: Sandbox Test Server
security:
- Bearer:
- client_credentials
tags:
- name: Partner-Merchant-Registration
x-displayName: Partner Merchant Registration
description: Below are the endpoints that enable you to create the necessary entities (Firm, Url, Shop, POS) for your partner.
paths:
/api/v2_1/firms:
post:
tags:
- Partner-Merchant-Registration
summary: Create a Firm
description: Create a Firm entity for your partner.
operationId: create-a-firm
security:
- Bearer:
- client_credentials
parameters:
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=client_credentials</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- type
- taxId
- taxIdType
- cin
- bankAccount
- partnerId
- businessArea
- users
- representatives
- contactData
- address
properties:
name:
type: string
description: Full legal name.
example: Test sp. z o.o.
type:
type: string
description: Dictionary value - legal entity type. Dictionaries for specific origin are available here. For a firm which <code>address.country</code> code is not equal to <code>businessArea.origin</code> please use <b>FZ</b> type. <b>Providing accurate type speeds up merchant verification.</b>
example: SO
taxId:
type: string
description: Tax identification.
example: '3771910486'
taxIdType:
type: string
description: Type of tax identification.
enum:
- NIP
- VAT_EU
- TAX_ID
example: NIP
cin:
type: string
description: Business identification. IČ (CZ) or REGON (PL).
example: '138237420'
bankAccount:
type: string
description: Primary bank account to receive payouts for payments. Will be inherited by all <b>shops</b> created for this firm. Must be a valid IBAN number in case of firms with <b>PL</b> origin. <b>Different bank account maybe defined at shop level manually, via PayU merchant panel.</b>
format: IBAN
example: PL92906300080597567560803897
partnerId:
type: string
description: Your partner id.
example: egmcvdo5
contactLanguage:
type: string
description: Preferred language for communication.
enum:
- EN
- PL
- CS
- RO
example: PL
businessArea:
type: object
required:
- origin
description: Business area of the registered firm.
properties:
origin:
type: string
description: 'Denotes firm origin and applies validation and requirements for this origin. Currently only two values are available: <b>CZ</b> and <b>PL</b>. <b>It is still possible to register a firm which is incorporated outside of Czechia or Poland</b>.'
example: PL
users:
type: array
description: Array of PayU panel users. At least 1 must be provided.
items:
type: object
required:
- name
- surname
- email
- role
properties:
name:
type: string
description: User's first name.
example: Jan
surname:
type: string
description: User's last name.
example: Nowak
email:
type: string
description: User's email.
example: jan.nowak@testowa.pl
phone:
type: string
description: User's phone number.
example: 123123123
role:
type: string
description: User's role.
enum:
- MANAGER
- USER
example: MANAGER
representatives:
type: array
description: Array of firm legal representatives. At least 1 must be provided.
items:
type: object
required:
- name
- surname
- countryCode
- birthCountryCode
properties:
name:
type: string
description: Representative's first name.
example: Jan
surname:
type: string
description: Representative's last name.
example: Nowak
nin:
type: string
description: Representative's national identity number (PESEL). <b>Required only for Polish citizens</b>
example: 80010104578
countryCode:
type: string
description: Representative's citizenship. Must be a valid ISO 3166-1 two-letter code.
example: PL
birthDate:
type: string
format: RRRR-MM-DD
description: Representative's date of birth. <b>Required only for non-Polish citizens</b>
example: '2000-01-01'
birthCountryCode:
type: string
description: Country code of representative's birth country. Must be a valid ISO 3166-1 two-letter code.
example: pl
contactData:
type: object
description: Object containing firm's contact details.
required:
- phone
- email
properties:
phone:
type: string
description: Firm's contact phone number.
example: 123123123
email:
type: string
description: Firm's contact email address.
example: biuro@testowa.pl
technicalContactData:
type: object
description: Object containing firm's technical contact details (e.g. to the developer responsible for integration with PayU).
required: []
address:
type: object
description: Firm's registration address.
required:
- street
- houseNo
- apartmentNo
- postalCode
- city
- countryCode
properties:
street:
type: string
description: Firm's registration address street.
example: Grunwaldzka
houseNo:
type: string
description: Firm's registration address house number.
example: 186
apartmentNo:
type: string
description: Firm's registration address apartment number.
example: 1
postalCode:
type: string
description: Firm's registration address postal code.
example: 61-166
city:
type: string
description: Firm's registration address city.
example: Poznań
countryCode:
type: string
description: Firm's registration address country code. Must be a valid ISO 3166-1 two-letter code.
example: PL
correspondenceAddress:
type: object
description: Firm's correspondence address (<b>if other than registration address</b>). This object the same fields as address.
required:
- street
- houseNo
- apartmentNo
- postalCode
- city
- countryCode
properties:
street:
type: string
description: Firm's registration address street.
example: Grunwaldzka
houseNo:
type: string
description: Firm's registration address house number.
example: 186
apartmentNo:
type: string
description: Firm's registration address apartment number.
example: 1
postalCode:
type: string
description: Firm's registration address postal code.
example: 61-166
city:
type: string
description: Firm's registration address city.
example: Poznań
countryCode:
type: string
description: Firm's registration address country code. Must be a valid ISO 3166-1 two-letter code.
example: PL
responses:
'200':
x-summary: OK
description: ''
content:
application/json:
schema:
type: object
properties:
firmId:
type: string
description: Identifier that needs to be stored in your system and is used to create further entities for that firm.
example: KzXy4ZzD
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/api/v2_1/firms/{firmId}/urls:
post:
tags:
- Partner-Merchant-Registration
summary: Create a URL for the Partner's Firm
description: Create a URL for the specified `firmId`.
operationId: create-a-url-for-the-partners-firm
security:
- Bearer:
- partner
parameters:
- name: firmId
in: path
example: KzXy4ZzD
description: Firm identifier retrieved after firm creation.
required: true
content:
application/json:
schema:
type: string
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=partner</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
requestBody:
content:
application/json:
schema:
type: object
required:
- value
- services
properties:
value:
type: string
description: URL address.
example: http://www.test-url.com
mcc:
type: string
description: Merchant Category Code (value is validated). Data type
example: '0742'
services:
type: array
description: Array of service types.
items:
type: object
required:
- type
properties:
type:
type: string
description: 'Dictionary value:<ul> <li><b>TRANSFERS</b> - online transfers ("pay-by-links" and standard bank transfers, incl. Blik),</li> <li><b>CARD</b> - cards (Visa, Mastercard) and digital wallets (Apple Pay, Google Pay),</li> <li><b>INSTALLMENTS</b> - online installments,</li> <li><b>DELAYED_PAYMENTS</b> - "pay later" methods.</li></ul>
'
enum:
- TRANSFERS
- CARD
- INSTALLMENTS
- DELAYED_PAYMENTS
example: TRANSFERS
responses:
'200':
x-summary: OK
description: ''
content:
application/json:
schema:
type: object
properties:
urlId:
type: string
description: urlId that needs to be stored in your system can be used to create shop.
example: PItR5x0v
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/api/v2_1/firms{firmId}/shops:
post:
tags:
- Partner-Merchant-Registration
summary: Create a Shop for the Partner
description: Create a Shop for the specified `firmId`.
operationId: create-a-shop-for-the-partner
security:
- Bearer:
- partner
parameters:
- name: firmId
in: path
example: KzXy4ZzD
description: Firm identifier retrieved after firm creation.
required: true
content:
application/json:
schema:
type: string
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=partner</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- currencyCode
- urlId
properties:
name:
type: string
description: Shop name - will be visible in the merchant panel.
example: Shop name
description:
type: string
description: Shop description - more detailed info, visible in the merchant panel.
example: Shop description
currencyCode:
type: string
description: Must be a three-letter ISO 4217 currency code. Please contact your key account manager to get more information about available currencies.
example: EUR
urlId:
type: string
description: Reference to previously created <b>URL</b>.
example: PItR5x0v
responses:
'200':
x-summary: OK
description: ''
content:
application/json:
schema:
type: object
properties:
shopId:
type: string
description: Identifier that needs to be stored in merchant's system and is used to create POS.
example: ycmGyfCv
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/api/v2_1/shops/{shopId}/poses:
post:
tags:
- Partner-Merchant-Registration
summary: Create POS for Partner
description: Create a POS, for your partner, for the specified `shopId`.
operationId: create-pos-for-partner
security:
- Bearer:
- partner
parameters:
- name: shopId
in: path
example: Shop identifier retrieved after shop creation.
required: true
content:
application/json:
schema:
type: string
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=partner</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- type
properties:
name:
type: string
description: Name of the created POS.
example: Test POS
type:
type: string
description: Type of the created POS.
example: REST
responses:
'200':
x-summary: OK
description: ''
content:
application/json:
schema:
type: object
properties:
posId:
type: string
description: Identifier of the created POS.
example: JyoMIVTY
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/api/v2_1/poses/{posId}:
get:
tags:
- Partner-Merchant-Registration
summary: Retrieve Partner's POS Data
description: Retrieve data of the POS with specified `posId`.
operationId: retrieve-partners-pos-data
security:
- Bearer:
- partner
parameters:
- name: posId
in: path
example: POS identifier retrieved after POS creation.
required: true
content:
application/json:
schema:
type: string
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=partner</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
responses:
'200':
x-summary: OK
description: ''
content:
application/json:
schema:
type: object
properties:
posId:
type: string
description: Public POS ID.
example: JyoMIVTY
type:
type: string
description: POS type (determines API that can be used).
example: REST
name:
type: string
description: POS name.
example: Test POS
encoding:
type: string
description: Determines encoding used by PayU system to read API requests. Always <b>UTF-8</b> for <b>REST</b> type.
example: UTF-8
authorization:
type: object
description: Object with authorization details.
properties:
standard:
type: object
properties:
merchantPosId:
type: string
description: POS identifier used for API calls. It has the same value as the `client_id` used in the OAuth calls.
example: '385234'
key:
type: string
description: Has the same value as the "`client_secret` used to obtain OAuth access tokens for REST API calls.
example: 9c0041e05fdee99749de4c2d2ce4c66e"
secondKey:
type: string
description: The second API key is utilized for signing notifications sent by PayU, as well as for verifying the notification signature provided by PayU. Additionally, it is used for basic authorization when fetching statement files via the API.
example: f096a39d78fbe03b8d23dde43b728cfd
authKey:
type: string
description: Not required for REST API.
example: uHcZ9Ly
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/api/v2_1/firms/{posId}/users:
post:
tags:
- Partner-Merchant-Registration
summary: Create a User
description: Create an additional User for your partner.
operationId: create-a-user
security:
- Bearer:
- partner
parameters:
- name: firmId
in: path
example: KzXy4ZzD
description: Firm identifier retrieved after firm creation.
required: true
content:
application/json:
schema:
type: string
- name: Content-Type
in: header
description: Content type
required: true
schema:
type: string
style: simple
example: application/json
- name: Authorization
in: header
description: Auth token with <code>grant_type=partner</code>.
required: true
schema:
type: string
style: simple
example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
requestBody:
content:
application/json:
schema:
type: object
required:
- user
properties:
user:
type: object
required:
- name
- surname
- email
- role
properties:
name:
type: string
minLength: 1
maxLength: 64
description: First name of the new user.
example: Joe
surname:
type: string
minLength: 1
maxLength: 64
description: Last name of the new user.
example: Doe
email:
type: string
minLength: 1
maxLength: 128
description: Email address of the new user.
example: joe.doe@test.com
phone:
type: string
minLength: 3
maxLength: 25
description: Phone number of the new user.
role:
type: string
enum:
- manager
- user
description: Role specified for the new user.
example: manager
responses:
'201':
x-summary: Created
description: ''
content:
application/json:
schema:
type: object
properties:
userId:
type: string
description: New user identifier.
example: 2e629a11-8add-49c5-bf27-a7f684721b86
'401':
x-summary: Unauthorized
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/401'
components:
schemas:
'401':
type: object
properties:
status:
type: object
properties:
statusCode:
type: string
description: Error type.
code:
type: string
description: Identification code of specific error.
codeLiteral:
type: string
description: Cause of the error.
statusDesc:
type: string
description: Error description.
securitySchemes:
Bearer:
type: http
scheme: bearer
Basic:
type: http
scheme: basic