Merchant

Create a new merchant

Create a new merchant within an organization. Requires ORGANIZATION_SETTINGS_ADD_MERCHANT permission.

post/api/v1/organizations/{organizationId}/merchants

Request

  • Base URL: https://api-sandbox.koywe.com
  • URL: https://api-sandbox.koywe.com/api/v1/organizations/{organizationId}/merchants
  • Auth: HTTP bearer

Path parameters

organizationIdstring required
Example:org_abc123

Organization identifier

Request body

countryIdstring required
defaultCurrencyIdstring

Example request

{
  "countryId": "ctry_84b8b218-2777-4e7f-863e-7d0601ac289f",
  "profile": {
    "name": "Galactic Republic Trading",
    "address": "123 Main St",
    "addressLine2": "Suite 100",
    "city": "Springfield",
    "postalCode": "90210",
    "stateId": "st_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "countyId": "cnt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "taxIdType": "RUC",
    "taxIdNumber": "123456789",
    "description": "1234 Main St, Coruscant",
    "email": "galactic.republic@row.com",
    "phone": "1234567890",
    "url": "https://galacticrepublic.com",
    "slug": "republic",
    "supportEmail": "galactic.republic@support.com",
    "supportPhone": "1234567890",
    "supportUrl": "https://galacticrepublic.com/support",
    "dateOfBirth": "1990-01-15",
    "nationalityCountrySymbol": "HK",
    "nationalityCountryId": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "defaultCurrencyId": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64",
  "settings": {
    "branding": {
      "icon": "https://galacticrepublic.com/icon",
      "logo": "https://galacticrepublic.com/logo",
      "primaryColor": "#000000",
      "secondaryColor": "#FFFFFF"
    },
    "dashboard": {
      "displayName": "Galactic Republic Trading",
      "timezone": "America/Argentina/Buenos_Aires"
    }
  },
  "billing": {
    "roundingType": "NET"
  }
}

Response

Merchant created successfully

merchantIdstring required
slugstring required
businessTypestring required
businessStructurestring required
chargesEnabledboolean required
countryIdstring required
createdAtstring date-time required
defaultCurrencyIdstring required
kybCompleteboolean required
disabledboolean required
disabledReasonstring required
lifecycleStatus'DRAFT' | 'ENABLED_LIMITED' | 'KYB_REQUIRED' | 'ACTIVE' | 'KYB_RENEWAL_REQUIRED' | 'REJECTED' required

Current lifecycle state of the merchant

canOperateboolean required

Whether the merchant can currently process transactions

validTransitionsstring[] required

Valid next states the merchant can transition to

Example response

{
  "merchantId": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc",
  "slug": "republic",
  "profile": {
    "name": "Galactic Republic Trading",
    "description": "1234 Main St, Coruscant",
    "address": "1234 Main St, Coruscant",
    "addressLine2": "Suite 100",
    "city": "Springfield",
    "postalCode": "90210",
    "state": "California",
    "stateId": "st_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "countyId": "cnt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email": "galactic.republic@row.com",
    "phone": "1234567890",
    "url": "https://galacticrepublic.com",
    "supportEmail": "galacticrepublic",
    "supportPhone": "1234567890",
    "supportUrl": "https://galacticrepublic.com/support",
    "taxIdType": "CUIT",
    "taxIdNumber": "123456789",
    "dateOfBirth": "1990-01-15T00:00:00.000Z",
    "nationalityCountryId": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "businessType": "Galactic Republic Trading",
  "businessStructure": "Galactic Republic Trading",
  "capabilities": {
    "payments": true,
    "collections": true
  },
  "chargesEnabled": true,
  "countryId": "ctry_84b8b218-2777-4e7f-863e-7d0601ac289f",
  "createdAt": "2024-07-01T22:40:22.003Z",
  "defaultCurrencyId": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64",
  "kybComplete": true,
  "disabled": true,
  "disabledReason": "N/D",
  "billing": {
    "roundingType": "NET"
  },
  "branding": {
    "icon": "https://example.com/icon.png",
    "logo": "https://example.com/logo.png",
    "primaryColor": "#FF0000",
    "secondaryColor": "#00FF00"
  },
  "lifecycleStatus": "ENABLED_LIMITED",
  "canOperate": true,
  "validTransitions": [
    "KYB_REQUIRED"
  ]
}

Changes

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