Skip to main content

Merchants

Weave 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_onboarding 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

File Upload​

Files 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 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 type of file being uploaded. Possible values: identity_document, asylum_document, passport, proof_of_address, bank_account_confirmation, cipc_registration_document, additional_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"
}
File Links

Supporting documentation that is self-hosted e.g. in an S3 bucket, can be referenced in File Upload API instead of providing the raw data.

Initiate a POST request to the https://api.stitch.money/v2/files URL to upload a file using a URL. Set the Content-Type header to application/json.

FieldTypeDescription
urlstringThe URL of the self-hosted file. Must be a non-empty string.
typestringIndicates the type of file being uploaded. Possible values: identity_document, asylum_document, passport, proof_of_address, bank_account_confirmation, cipc_registration_document, additional_document.

The response contains a file id.

{
  "id": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=",
  "file": {
      "url": "https://myurl.com"
  }
}

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/v2/merchants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "externalReference": "demo-merchant-001",
    "businessType": "company",
    "countryCode": "ZA",
    "company": {
      "name": "Stitch Demo Retail Ltd",
      "categoryCode": "5611",
      "phone": "+27123456789",
      "url": "https://stitchdemo.co.za",
      "email": "demo@stitchdemo.co.za",
      "address": {
        "street": "123 Main Street",
        "city": "Cape Town",
        "postalCode": "8001",
        "regionCode": "WC",
        "countryCode": "ZA"
      },
      "bankAccount": {
        "number": "1234567890",
        "bank": "fnb",
        "accountHolderName": "Stitch Demo Retail Ltd"
      },
      "verification": {
        "status": "verified",
        "registrationNumber": "2020/123456/07",
        "registrationDate": "2020-02-15",
        "legalName": "Stitch Demo Retail Ltd",
        "taxNumber": "9876543210",
        "directors": [
          {
            "idType": "identity_document",
            "idNumber": "8001015009083",
            "name": "John Smith",
            "dateOfBirth": "1980-01-01",
            "gender": "male",
            "nationality": "ZA",
            "phone": "+27123456789",
            "email": "demo@stitchdemo.co.za",
            "address": {
              "street": "123 Main Street",
              "city": "Cape Town",
              "postalCode": "8001",
              "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. Use company for Close Corporations.
companyCompanyCompany object for company information.
individualIndividual (optional)Individual object for sole proprietor information.
documentsarrayList of supporting documentation.
documents[].idstringUnique ID of the uploaded document.

Company Fields

FieldTypeDescription
namestringThe company's trading name.
categoryCodestringThe merchant category code (MCC).
phonestringThe company's phone number in E.164 format.
urlstring (optional)The company's website URL.
emailstring (optional)The company's email address.
address.streetstringThe registered street address.
address.citystringThe registered city.
address.postalCodestringThe registered postal code.
address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape).
address.countryCodestringISO 3166-1 alpha-2 country code.
bankAccount.numberstringThe bank account number.
bankAccount.bankstringThe bank name. Must be a valid BankBeneficiaryBankId value.
bankAccount.accountHolderNamestringThe account holder's name.
bankAccount.verificationResultstring (optional)Third-party Account Verification Service result.
metadataobject (optional)Arbitrary metadata associated with the company.
verification.statusstringPossible values: verified or not_verified.
verification.verificationProviderstring (optional)The external verification provider.
verification.verificationProviderIdstring (optional)A reference ID returned by the verification provider.
verification.registrationNumberstringThe CIPC registration number.
verification.registrationDatestringISO8601 date string.
verification.legalNamestringThe company's registered legal name.
verification.taxNumberstringThe company's tax identification number.
verification.risk.ratingstringA Client-assigned risk rating for the merchant. Possible values: low, medium or high.
verification.risk.screenbooleanSanction and/or PEP/PIP screening conducted.
verification.risk.vmssboolean (optional)Visa Merchant Screening Service check conducted.
verification.risk.matchboolean (optional)Mastercard MATCH check conducted.
verification.directorsarray (optional)Array of Director objects.
verification.beneficialOwnersarray (optional)Array of beneficial owners. Uses the Director schema.
verification.authorizedSignatoriesarray (optional)Array of authorized signatories. Uses the Director schema.
verification.membersarray (optional)Array of Closed Corporation members. Uses the Director schema.

Director Fields

FieldTypeDescription
idTypestringThe identification type. Possible values: passport, identity_document or asylum_document.
idNumberstringThe national ID or passport number.
namestringThe director's full legal name.
dateOfBirthstringThe director's date of birth in format YYYYMMDD.
genderstringThe director's gender.
nationalitystringISO 3166-1 alpha-2 country code.
phonestring (optional)The director's phone number in E.164 format.
emailstring (optional)The director's email address.
address.streetstringThe director's registered street address.
address.citystringThe director's registered city.
address.postalCodestringThe director's registered postal code.
address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape).
address.countryCodestringISO 3166-1 alpha-2 country code.
risk.screenbooleanSanction and/or PEP/PIP screening conducted.
risk.dhabooleanDepartment of Home Affairs (South Africa) query conducted.
metadataobject (optional)Arbitrary metadata.

Individual Fields

FieldTypeDescription
idTypestringThe identification type. Possible values: passport, identity_document or asylum_document.
idNumberstringThe national ID or passport number.
namestringThe individual's full legal name.
dateOfBirthstringThe individual's date of birth in format YYYYMMDD
genderstringThe individual's gender
nationalitystringISO 3166-1 alpha-2 country code.
phonestringThe individual's phone number in E.164 format.
emailstringThe individual's email address.
address.streetstringThe individual's registered street address.
address.citystringThe individual's registered city.
address.postalCodestringThe individual's registered postal code.
address.regionCodestringISO 3166-2 region code (e.g., "WC" for Western Cape)
address.countryCodestringISO 3166-1 alpha-2 country code.
verification.statusstringPossible values: verified or not_verified.
verification.providerstring (optional)The external verification provider.
verification.providerIdstring (optional)A unique reference ID returned by the verification provider.
metadataobject (optional)Arbitrary metadata.

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": "demo-merchant-001",
  "businessType": "company",
  "countryCode": "ZA",
  "mid": "991234567890123456",
  "name": "Stitch Demo Retail Ltd",
  "categoryCode": "5611",
  "phone": "+27123456789",
  "url": "https://stitchdemo.co.za",
  "email": "demo@stitchdemo.co.za",
  "address": {
    "street": "123 Main Street",
    "city": "Cape Town",
    "postalCode": "8001",
    "regionCode": "WC",
    "countryCode": "ZA"
  },
  "bankAccount": {
    "number": "1234567890",
    "bank": "fnb",
    "accountHolderName": "Stitch Demo Retail Ltd"
  },
  "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"
}
{
  "title": "Invalid Input",
  "code": "BAD_USER_INPUT",
  "detail": "Failed to create merchant. Missing required documents: proof_of_address, bank_account_confirmation, cipc_registration_document"
}

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=demo-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.
businessTypeThe merchant's business type.
externalReferenceA unique identifier provided by the client to reference or filter specific records.
midA unique MID assigned by Stitch.
statusThe merchant's status on the Stitch platform.
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.stitch.money/v2/merchants/bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk= \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "company": {
      "name": "New Stitch Demo Retail Ltd",
      "phone": "+27123456788",
      "url": "https://newstitchdemo.co.za",
      "email": "demo@newstitchdemo.co.za",
      "address": {
        "street": "123 New Street",
        "city": "Cape Town",
        "postalCode": "8001",
        "regionCode": "WC",
        "countryCode": "ZA"
      },
      "bankAccount": {
        "number": "1234567890",
        "bank": "fnb",
        "accountHolderName": "New Stitch Demo Retail Ltd"
      }
    }
  }'

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