Skip to main content

Merchants

Connect allows clients to register and manage merchants on the Stitch platform. A merchant is a registered entity for which the client processes transactions on their behalf.

Each merchant is assigned a unique Merchant ID (MID) generated by Stitch and must be verified before they can transact. If a merchant has been pre-verified, the business verification data can be submitted to Stitch via the API. Contact support@stitch.money for more information on pre-verification.

Integration Overview​

Follow the steps described in the client token guide to obtain a client token with the client_merchant_manage scope.

The Stitch REST API URL https://api.stitch.money/v2/merchants can be used for all merchant management requests.

Merchant Registration​

The initial step involves registering a merchant on the platform. The following information must be submitted on registration:

  • Basic Information: The merchant's trading name and contact information
  • Business Type: The merchant's business structure i.e. sole proprietorship or business entity
  • Business Classification: The Merchant Category Code (MCC) that identifies the category of business.
  • Address Details: The merchant's physical address and region
  • Bank Account: The merchant's bank account details for settlement

Document Upload​

Documents can be uploaded to Stitch and referenced during merchant creation. The Upload File API returns a id that can be included in the documents array.

Initiate a POST request to the https://api.stitch.money/v2/files URL to upload a file. This API follows the RFC 2388 specification for defining a file. Set the Content-Type header to multipart/form-data.

curl --location 'https://api.stitch.money/v2/files' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'file=@"postman-cloud:///1f050393-ec6f-46b0-88bc-75947ec7cb9b"' \
--form 'type="identity_document"'
FieldTypeDescription
file.namestringThe name of the uploaded file. Must be a non-empty string.
file.typestringThe MIME type of the file. Only application/pdf, image/jpeg and image/png are supported.
file.dataanyThe raw binary content of the file.
typestringIndicates the purpose of the file being uploaded. Possible values: verification_document or identity_document.

The file is uploaded to Stitch's server and securely stored. The response contains a file id and associated metadata in the file object.

{
  "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=",
  "file": {
      "name": "id.png",
      "type": "application/pdf",
      "size": "1024"
  }
}

Stitch returns an error response in the following format if the file is not uploaded successfully:

{
  "title": "Internal Server Error",
  "code": "INTERNAL_SERVER_ERROR",
  "detail": "Failed to upload file. Please try again later"
}

Merchant Creation​

Stitch supports two business verification options: verified and not_verified. Set the company.verification.status field in the request body to verified if Know Your Business (KYB) checks have been performed. The verified information must be submitted in the request for validation.

Use not_verified if the merchant has not been pre-verified. Stitch conducts the relevant KYB checks and activates the merchant once compliance requirements have been satistifed. The registrationNumber field is required for both scenarios.

Verification Data

The company.verification object is not required if the business is a sole proprietorship i.e. the businessType is set to individual. Instead, the individual object must be populated in the request.

Initiate a POST request to the https://api.stitch.money/v2/merchants URL to create a merchant for a registered company or individual. Set the Content-Type header to application/json.

curl -X POST https://api.stitch.money/merchants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "externalReference": "merchant-001",
    "businessType": "company",
    "countryCode": "ZA",
    "company": {
      "name": "Blue Crane Retail Ltd.",
      "categoryCode": "5611",
      "phone": "+27831234567",
      "url": "https://bluecraneretail.co.za",
      "address": {
        "street": "10 Bree Street",
        "city": "Cape Town",
        "postalCode": "8001",
        "regionCode": "WC",
        "countryCode": "ZA"
      },
      "bankAccount": {
        "number": "1234567890",
        "bank": "fnb",
        "accountHolderName": "Blue Crane Retail Ltd."
      },
      "verification": {
        "status": "verified",
        "registrationNumber": "2020/123456/07",
        "registrationDate": "2020-02-15",
        "legalName": "Blue Crane Retail Ltd.",
        "taxNumber": "9876543210",
        "directors": [
          {
            "name": "Thabo Mokoena",
            "dateOfBirth": "1980-07-12",
            "gender": "male",
            "nationality": "ZA",
            "phone": "+27831234568",
            "email": "lilo@bluecraneretail.co.za",
            "address": {
              "street": "21 Long Street",
              "city": "Cape Town",
              "postalCode": "8000",
              "regionCode": "WC",
              "countryCode": "ZA"
            }
          }
        ]
      }
    },
    "documents": [
      { "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=" }
    ]
  }'
FieldTypeDescription
externalReferencestring (optional)A unique reference for the merchant provided by the client.
metadataobject (optional)Arbitrary key-value metadata associated with the merchant.
businessTypestringPossible values: individual or company.
countryCodestringISO 3166-1 alpha-2 country code (e.g., "ZA").
company.namestringThe company's trading name.
company.categoryCodestringThe merchant category code (MCC).
company.phonestringThe company's phone number in E.164 format.
company.urlstring (optional)The company's website URL.
company.address.streetstringThe registered street address.
company.address.citystringThe registered city.
company.address.postalCodestringThe registered postal code.
company.address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape).
company.address.countryCodestringISO 3166-1 alpha-2 country code.
company.bankAccount.numberstringThe bank account number.
company.bankAccount.bankstringThe bank name. Must be a valid BankBeneficiaryBankId value.
company.bankAccount.accountHolderNamestringThe account holder's name.
company.metadataobject (optional)Arbitrary metadata associated with the company.
company.verification.statusstringPossible values: verified or not_verified.
company.verification.verificationProviderstring (optional)The external verification provider.
company.verification.verificationProviderIdstring (optional)A reference ID returned by the verification provider.
company.verification.registrationNumberstringThe CIPC registration number.
company.verification.registrationDatestringISO8601 date string.
company.verification.legalNamestringThe company's registered legal name.
company.verification.taxNumberstringThe company's tax identification number.
company.verification.directorsarray (optional)Array of director objects.
company.verification.directors[].namestringThe director's full legal name.
company.verification.directors[].dateOfBirthstringThe director's date of birth in format YYYYMMDD.
company.verification.directors[].genderstringThe director's gender.
company.verification.directors[].nationalitystringISO 3166-1 alpha-2 country code.
company.verification.directors[].phonestring (optional)The director's phone number in E.164 format.
company.verification.directors[].emailstring (optional)The director's email address.
company.verification.directors[].address.streetstringThe director's registered street address.
company.verification.directors[].address.citystringThe director's registered city.
company.verification.directors[].address.postalCodestringThe director's registered postal code.
company.verification.directors[].address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape).
company.verification.directors[].address.countryCodestringISO 3166-1 alpha-2 country code.
company.verification.directors[].metadataobject (optional)Arbitrary metadata.
company.verification.beneficialOwnersarray (optional)Array of beneficial owner objects. The schema is identical to the directors.
individual.idTypestringThe identification type. Possible values: passport or identity_document.
individual.idNumberstringThe national ID or passport number.
individual.namestringThe individual's full legal name.
individual.dateOfBirthstringThe individual's date of birth in format YYYYMMDD
individual.genderstringThe individual's gender
individual.nationalitystringISO 3166-1 alpha-2 country code.
individual.phonestringThe individual's phone number in E.164 format.
individual.emailstringThe individual's email address.
individual.address.streetstringThe individual's registered street address.
individual.address.citystringThe individual's registered city.
individual.address.postalCodestringThe individual's registered postal code.
individual.address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape)
individual.address.countryCodestringISO 3166-1 alpha-2 country code
individual.verification.verificationStatusstringPossible values: verified or not_verified.
individual.verification.verificationProviderstring (optional)The external verification provider.
individual.verification.verificationProviderIdstring (optional)A unique reference ID returned by the verification provider.
individual.metadataobject (optional)Arbitrary metadata.
documentsarray (optional)Array of documents.
documents[].idstringUnique ID of the uploaded document.

The response includes the merchant id, the merchant's status and MID. The status field indicates that merchant verification has been completed or not. A merchant must be in an active state in order to transact.

Merchant IDs

The mid field contains the unique processing MID assigned by Stitch and references the merchant's Stitch Acquiring account. The id field is the Stitch API resource identifier and must be used for subsequent operations.

{
  "id": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
  "status": "active",
  "externalReference": "merchant-001",
  "businessType": "company",
  "countryCode": "ZA",
  "mid": "991234567890123456",
  "company": {
    "name": "Blue Crane Retail Ltd.",
    "categoryCode": "5611",
    "phone": "+27831234567",
    "url": "https://bluecraneretail.co.za",
    "address": {
      "street": "10 Bree Street",
      "city": "Cape Town",
      "postalCode": "8001",
      "regionCode": "WC",
      "countryCode": "ZA"
    },
    "bankAccount": {
      "number": "1234567890",
      "bank": "fnb",
      "accountHolderName": "Blue Crane Retail Ltd."
    },
    "verification": {
      "status": "verified",
      "registrationNumber": "2020/123456/07",
      "registrationDate": "2020-02-15",
      "legalName": "Blue Crane Retail Ltd.",
      "taxNumber": "9876543210",
      "directors": [
        {
          "name": "Thabo Mokoena",
          "dateOfBirth": "1980-07-12",
          "gender": "male",
          "nationality": "ZA",
          "phone": "+27831234568",
          "email": "thabo@bluecraneretail.co.za",
          "address": {
            "street": "21 Long Street",
            "city": "Cape Town",
            "postalCode": "8000",
            "regionCode": "WC",
            "countryCode": "ZA"
          }
        }
      ]
    }
  },
  "documents": [
    {
      "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM="
    }
  ]
}


Stitch returns an error response in the following format if the merchant is not created successfully:

{
  "title": "Internal Server Error",
  "code": "INTERNAL_SERVER_ERROR",
  "detail": "Failed to create merchant. Please try again later"
}

Merchant Retrieval​

Initiate a GET request to retrieve a specific merchant by ID:

curl -X GET 'https://api.stitch.money/v2/merchants/bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk=' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

The response object is identical in structure to the one returned by the POST request used to create a merchant.

You can list multiple merchants and filter the results using query parameters, such as externalReference:

curl -X GET 'https://api.stitch.money/v2/merchants?externalReference=merchant-001' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

The response includes a data field containing an array of merchant objects that match the specified filters.

Retrieval is paginated and supports the offset and limit query parameters to control result size and pagination. The default page size is 2000. A paginated query example is indicated below:

curl -X GET 'https://api.stitch.money/v2/merchants?limit=50&offset=100' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Query Parameters

ParameterDescription
offsetThe number of records to skip before starting to return results. Used for pagination.
limitThe maximum number of records to return in the response. Used to control page size.
externalReferenceA unique identifier provided by the client to reference or filter specific records.
midA unique MID assigned by Stitch
Query Paging

The default page size is 2000. Use the limit field to reduce the number of records returned in a single response.

Merchant Management​

Initiate a PATCH request to update merchant data, including address information and bank account details. Note that all fields are optional.

curl -X PATCH https://api.example.com/merchants/bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk= \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "company": {
      "name": "New Company Name",
      "phone": "+27831234567",
      "url": "https://newcompany.co.za",
      "address": {
        "street": "123 New Street",
        "city": "Cape Town",
        "postalCode": "8001",
        "regionCode": "WC",
        "countryCode": "ZA"
      },
      "bankAccount": {
        "number": "1122334455",
        "bank": "fnb",
        "accountHolderName": "New Company Name"
      }
    }
  }'

The response object is identical in structure to those returned by the POST and GET operations.