Show Merchant

GET 
/v1/merchants/:merchantId

Get a specific merchant

Request

Path Parameters

merchantId uuidrequired

Responses

200

Successful response

application/json

Schema

Schema

id uuid

Merchant ID. Used only with Platform API.

entity_id uuid

Entity ID (Merchant Account). This ID is used with all other APIs.

type MerchantTypes (string)

Possible values: [freelancer, establishment, company, foreign_company, government, charity]

Merchant type determine the goverment category for the onboarded merchant and also affects the required KYC documents.

status string

Possible values: [pending, missing_docs, under_review, semi_active, active, hold, rejected, disabled]

Merchant current status.

The status missing_docs indicates that there are required changes that must be done for the merchant which can be found in reasons. After fixing the issues, the merchant must be submitted again for review.

name string

Merchant name

website uri
email email
created_at date-time
updated_at date-time
statement_descriptor string

Merchant name that will appear on the cardholder statement.

owners_count integer
signatory string
signatory_count integernullable
documents_complete boolean

Indicate if all required documents has been uploaded.

signature

object

status string

Possible values: [unsigned, initiated, signed]

url uri

api_keys

object

Entity's API keys.

test

object

publishable_key string

Account publishable API key.

secret_key string

Account secret API key.

This key will only be returned once during merchant created. You must this key securely within your infrastructure.

There no way to view this key again, it must be regenerated using the Regenerate Key endpoint.

live

object

publishable_key string

Account publishable API key.

secret_key string

Account secret API key.

This key will only be returned once during merchant created. You must this key securely within your infrastructure.

There no way to view this key again, it must be regenerated using the Regenerate Key endpoint.

fees

object[]

Array [

name string

Fee type name

rate string

Variable charge rate

fixed string

Fixed charge fee

]

enabled_schemes string[]

Possible values: [mada, visa, master]

Enabled schemes for this merchants.

payment_methods string[]

Possible values: [creditcard, applepay, samsungpay, googlepay, stcpay]

Enabled payment methods for this merchant.

required_documents

object[]

Array [

type DocumentType (string)

Possible values: [activity_license, bank_iban_certificate, commercial_registration, company_address, freelance_certificate, investment_license, official_letter, owner_address, owner_id, power_of_attorney, signatory_address, signatory_id, vat_certificate, memorandum_of_association, other]

info

object

oneOf

ActivityLicenseInfo

Activity License. Needed when the activity in CR requires one.

number string

Possible values: <= 255 characters

Activity license number.

BankCertificateInfo

Official Bank IBAN Certificate

holder stringrequired

Possible values: <= 255 characters

IBAN holder person/entity name as registered on bank records.

iban stringrequired

Possible values: >= 24 characters and <= 24 characters, Value must match regular expression ^SA\d{22}$

Valid IBAN number for the card holder

CommercialRegistrationInfo

Commercial Registration for the merchant business.

number stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[17]\d{9}$

Must be a valid CR number (starts with 1) or a valid unified number (starts with 7).

CompanyAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

OwnerAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

SignatoryAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

FreelanceCertificateInfo

Freelance Certificate

number stringrequired

Possible values: <= 255 characters

Freelance certificate number.

expiry_date daterequired

InvestmentLicenseInfo

Investment License issued by the Ministry of Investment

number stringrequired

Possible values: <= 255 characters

Investment license number.

expiry_date daterequired

OwnerIdInfo

National/Expat ID of the business owner.

id stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[12]\d{9}$

A valid Saudi or Expat government ID

mobile stringrequired

Possible values: >= 10 characters and <= 10 characters

A valid Saudi mobile number

date_of_birth daterequired

SignatoryIdInfo

National/Expat ID of the authorized signatory.

id stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[12]\d{9}$

A valid Saudi or Expat government ID

mobile stringrequired

Possible values: >= 10 characters and <= 10 characters

A valid Saudi mobile number

date_of_birth daterequired

PowerOfAttorneyInfo

Power of Attorney issued by the Ministry of Justice that gives a person the ability to sign on agreements.

number stringrequired

Possible values: <= 255 characters

Power of Attorney reference number.

VatCertificateInfo

VAT certificate if the business is required to pay taxes by law. The name must match the one in Commercial Registration.

number stringrequired

Possible values: <= 255 characters

Investment license number.

OtherInfo

Any type of document that is not categorized.

description required

requires_upload boolean

Indicate if the document type requires a file to be attached.

required_count integer

The minimum number of required documents of the same type. E.g. when specifying 5 owners, then 5 owner IDs must be added using the Upload Document endpoint.

]

comment string

Comment left by the onboarding team related to the merchant status.

reasons string[]

List of reasons on why the merchant was rejected or changes were requested (missing_docs).

documents

object[]

Array [

id uuid

type DocumentType (string)

Possible values: [activity_license, bank_iban_certificate, commercial_registration, company_address, freelance_certificate, investment_license, official_letter, owner_address, owner_id, power_of_attorney, signatory_address, signatory_id, vat_certificate, memorandum_of_association, other]

info

object

oneOf

ActivityLicenseInfo

Activity License. Needed when the activity in CR requires one.

number string

Possible values: <= 255 characters

Activity license number.

BankCertificateInfo

Official Bank IBAN Certificate

holder stringrequired

Possible values: <= 255 characters

IBAN holder person/entity name as registered on bank records.

iban stringrequired

Possible values: >= 24 characters and <= 24 characters, Value must match regular expression ^SA\d{22}$

Valid IBAN number for the card holder

CommercialRegistrationInfo

Commercial Registration for the merchant business.

number stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[17]\d{9}$

Must be a valid CR number (starts with 1) or a valid unified number (starts with 7).

CompanyAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

OwnerAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

SignatoryAddressInfo

Official Proof of National Address for the merchant business.

name string

Possible values: <= 255 characters

street string

Possible values: <= 255 characters

district string

Possible values: <= 255 characters

building_number string

Possible values: <= 255 characters

secondary_number string

Possible values: <= 255 characters

postal_code string

Possible values: <= 255 characters

city string

Possible values: <= 255 characters

country Country (string)

ISO-3166-1 alpha-2 country code.

FreelanceCertificateInfo

Freelance Certificate

number stringrequired

Possible values: <= 255 characters

Freelance certificate number.

expiry_date daterequired

InvestmentLicenseInfo

Investment License issued by the Ministry of Investment

number stringrequired

Possible values: <= 255 characters

Investment license number.

expiry_date daterequired

OwnerIdInfo

National/Expat ID of the business owner.

id stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[12]\d{9}$

A valid Saudi or Expat government ID

mobile stringrequired

Possible values: >= 10 characters and <= 10 characters

A valid Saudi mobile number

date_of_birth daterequired

SignatoryIdInfo

National/Expat ID of the authorized signatory.

id stringrequired

Possible values: >= 10 characters and <= 10 characters, Value must match regular expression ^[12]\d{9}$

A valid Saudi or Expat government ID

mobile stringrequired

Possible values: >= 10 characters and <= 10 characters

A valid Saudi mobile number

date_of_birth daterequired

PowerOfAttorneyInfo

Power of Attorney issued by the Ministry of Justice that gives a person the ability to sign on agreements.

number stringrequired

Possible values: <= 255 characters

Power of Attorney reference number.

VatCertificateInfo

VAT certificate if the business is required to pay taxes by law. The name must match the one in Commercial Registration.

number stringrequired

Possible values: <= 255 characters

Investment license number.

OtherInfo

Any type of document that is not categorized.

description required

file_uploaded boolean

]

Example (from schema)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "freelancer",
  "status": "pending",
  "name": "Chocolate Factory",
  "website": "https://example.com",
  "email": "[email protected]",
  "created_at": "2024-07-29T15:51:28.071Z",
  "updated_at": "2024-07-29T15:51:28.071Z",
  "statement_descriptor": "CHOCO",
  "owners_count": 0,
  "signatory": "string",
  "signatory_count": 0,
  "documents_complete": true,
  "signature": {
    "status": "initiated",
    "url": "https://example.moyasar.com/nafath-signing-page"
  },
  "api_keys": {
    "test": {
      "publishable_key": "string",
      "secret_key": "string"
    },
    "live": {
      "publishable_key": "string",
      "secret_key": "string"
    }
  },
  "fees": [
    {
      "name": "cc_charge_rate",
      "rate": 2.75,
      "fixed": 0.5
    }
  ],
  "enabled_schemes": [
    "mada",
    "visa",
    "master"
  ],
  "payment_methods": [
    "creditcard",
    "applepay",
    "samsungpay",
    "googlepay"
  ],
  "required_documents": [
    {
      "type": "activity_license",
      "requires_upload": true,
      "required_count": 1
    }
  ],
  "comment": "This merchant line of work requires an activity license from FDA.",
  "reasons": [
    "string"
  ],
  "documents": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "activity_license",
      "file_uploaded": true
    }
  ]
}

401

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [authentication_error]

message string

Possible values: [Invalid authorization credentials]

errors object

Example (from schema)

{
  "type": "authentication_error",
  "message": "Invalid authorization credentials",
  "errors": null
}

403

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [api_error]

message string

Possible values: [User not authorized]

errors object

Example (from schema)

{
  "type": "api_error",
  "message": "User not authorized",
  "errors": null
}

404

One of the record referenced in the request was not found

application/json

Schema

Schema

type string

Possible values: [record_not_found]

message string
errors object

Example (from schema)

{
  "type": "record_not_found",
  "message": "The <object type> record you were looking for was not found.",
  "errors": null
}

Loading...