PIpismo
Merchant

Create merchant

Create merchant. You use this endpoint to register a merchant (store) in a marketplace using the information the merchant provides.

<b>Note:</b> Before you create merchants, you must create a Merchant program, using the Create program based on template endpoint with type set to MERCHANT. If a program of type MERCHANT is not provided, the request returns an error. By default, when a merchant is created, the Pismo platform assigns it to the first existing program of type MERCHANT in the Org. However, you have the option of specifying a program by providing its ID in the program_id field.

<b>Note:</b> When a x-marketplace-id header is provided, the merchant is automatically linked to the provided marketplace after creation.

For more information about merchants, refer to the <a href="https://developers.pismo.io/pismo-docs/docs/seller-management-overview" target="blank">Seller management overview</a> guide.<br>

This endpoint generates a Merchant created event.

post/v1/merchants

Request

  • Base URL
    https://sandbox.pismolabs.io/merchants
  • URL
    https://sandbox.pismolabs.io/merchants/v1/merchants
  • Auth
    HTTP bearer

Headers

Content-Typestring
Example:application/json

Content type

Authorizationstring
Example:Bearer 1JI12J39182H39182JDIOAWJ%=

Authorization token. This is a regular access token, which does not need to include an account ID.

x-marketplace-idinteger
Example:123456

Marketplace ID

Request body

document_numberstring required

Merchant document number. This is the government document code, such as a government-issued tax ID.

namestring required

Merchant name

emailstring required

Email address

brand_namestring

Merchant brand name. Note that this is different from a merchant's legal registered name. For example, <i>Great Company</i> as opposed to <i>Great Company, LLC</i> (legal entity name).

municipal_registrationstring

Merchant's municipal registration number

contactstring

Name of contact

zip_codestring

Postal code. This is called a zip code in the United States, but you can use other types of postal codes.

numberinteger

Numerical identifier for the specific location within a street or avenue

addressstring

Name of the street, avenue, or primary thoroughfare of the address

complementary_addressstring

Additional address details that help pinpoint the exact location, such as building, apartment, or floor

neighborhoodstring

Name of the neighborhood or administrative region where the address is located

statestring

Abbreviation or full name of the state, province, or administrative division

citystring

Name of the city or municipality

countrystring

Full name of the country according to international standards or local registry

area_codestring

Area code. The US, Canada, and certain other countries divide their telephone service into regions, which are identified by numbers called area codes. In the US, for example, area codes are 3-digit numbers.

phonestring

Phone number. Parentheses and dashes are optional.

additional_area_codestring

Additional area code (for additional_phone)

additional_phonestring

Number for an additional phone. Parentheses and dashes are optional.

program_idinteger

Program ID for merchant account

external_codestring

Code for merchant category. The category is the type of business. You can use the endpoint <a href="https://developers.pismo.io/pismo-docs/reference/get_v1-businesscategories">Retrieves business categories corresponding to query parameters</a> to get a list of business categories and their external codes.

external_idstring

Internal ID used by client to reference a merchant in their domain.

city_codestring

Official seven-digit numeric code of the city according to the IBGE (Brazilian Institute of Geography and Statistics) code table. Used only for cities in Brazil; this code is unique per city.

Example request

{
  "document_number": "40533164000107",
  "name": "Acme Store",
  "email": "test@acmecorp.com",
  "brand_name": "Acme Corporation",
  "municipal_registration": "737.326.648.860",
  "contact": "John Doe",
  "zip_code": "12345",
  "number": 45,
  "address": "Maple Street",
  "complementary_address": "Suite 100",
  "neighborhood": "Canary Wharf",
  "state": "CA",
  "city": "San Diego",
  "country": "United States",
  "area_code": "555",
  "phone": "1231234",
  "additional_area_code": "11",
  "additional_phone": "2342345",
  "program_id": 123,
  "external_id": "5321",
  "creditor": {
    "name": "Acme Corporation",
    "id": 1,
    "crediting_method": "ACCOUNT",
    "advancement_fee": "30.00",
    "discount_rate": "0.03",
    "maximum_advancement_percentage": "0.80"
  },
  "city_code": "3550308"
}

Response

Created

idinteger

Merchant ID

document_numberstring

Merchant document number. This is the government document code, such as a government-issued tax ID.

namestring

Merchant name

brand_namestring

Merchant brand name. Note that this is different from a merchant's legal registered name. For example, <i>Great Company</i> as opposed to <i>Great Company, LLC</i> (legal entity name).

municipal_registrationstring

Merchant's municipal registration number

categorystring

Code name for merchant category. The category is the type of business.

contactstring

Name of contact

emailstring

Email address

zip_codestring

Postal code. This is called a zip code in the United States, but you can use other types of postal codes.

addressstring

Name of the street, avenue, or primary thoroughfare of the address

complementary_addressstring

Additional address details that help pinpoint the exact location, such as building, apartment, or floor

neighborhoodstring

Name of the neighborhood or administrative region where the address is located

statestring

Abbreviation or full name of the state, province, or administrative division

citystring

Name of the city or municipality

countrystring

Full name of the country according to international standards or local registry

numberinteger

Numerical identifier for the specific location within a street or avenue

area_codestring

Area code. The US, Canada, and certain other countries divide their telephone service into regions, which are identified by numbers called area codes. In the US, for example, area codes are 3-digit numbers.

phonestring

Phone number. Parentheses and dashes are optional.

additional_area_codestring

Additional area code (for additional_phone)

additional_phonestring

Number for an additional phone. Parentheses and dashes are optional.

program_idinteger

Program ID for merchant account

external_codestring

Code for merchant category. The category is the type of business. You can use the endpoint <a href="https://developers.pismo.io/pismo-docs/reference/get_v1-businesscategories">Retrieves business categories corresponding to query parameters</a> to get a list of business categories and their external codes.

external_idstring

Internal ID used by client to reference a merchant in their domain.

Example response

{
  "id": 9278,
  "document_number": "40533164000107",
  "name": "Acme Corporation",
  "brand_name": "Acme",
  "municipal_registration": "737.326.648.860",
  "category": "123",
  "contact": "John Doe",
  "email": "test@acmecorp.com",
  "zip_code": "12345",
  "address": "Maple Street",
  "complementary_address": "Suite 100",
  "neighborhood": "Canary Wharf",
  "state": "CA",
  "city": "San Diego",
  "country": "United States",
  "number": 223,
  "area_code": "555",
  "phone": "1231234",
  "additional_area_code": "11",
  "additional_phone": "2342345",
  "program_id": 123,
  "external_code": "abc-123",
  "external_id": "5324",
  "city_code": "3550308",
  "creditor": {
    "id": 7611,
    "name": "Acme Corporation",
    "crediting_method": "ACCOUNT",
    "account": {
      "id": 2
    },
    "advancement_fee": "3.00",
    "discount_rate": "0.025",
    "maximum_advancement_percentage": "0.80"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.