---
updatedAt: 2025-10-16T13:03:12.000Z
---

# /wallet/merchantonboarding/v1

Creates a new merchant entity in Merchant System of Record with a unique MerchantID. This ID is then used to identify the merchant in Paze.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Paze Merchants API",
    "description": "Paze API for merchant onboarding",
    "version": "1.0.0-oas3.1"
  },
  "servers": [
    {
      "url": "https://api.paze.com",
      "description": "Base URL for Paze APIs"
    }
  ],
  "security": [
    {
      "OAuth2": []
    }
  ],
  "paths": {
    "/wallet/merchantonboarding/v1": {
      "post": {
        "tags": [
          "Merchant Onboarding"
        ],
        "description": "Creates a new merchant entity in Merchant System of Record with a unique MerchantID. This ID is then used to identify the merchant in Paze.",
        "operationId": "createMerchant",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MerchantOnboardRequest"
              },
              "examples": {
                "MerchantsPostRequestExample": {
                  "$ref": "#/components/examples/MerchantsPostRequestExample"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantResponse"
                },
                "examples": {
                  "MerchantsPost201ResponseExample": {
                    "$ref": "#/components/examples/MerchantsPost201ResponseExample"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                },
                "examples": {
                  "MerchantsErrorExample": {
                    "$ref": "#/components/examples/MerchantsError404Example"
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                },
                "examples": {
                  "MerchantsErrorExample": {
                    "$ref": "#/components/examples/MerchantsError409Example"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                },
                "examples": {
                  "MerchantsErrorExample": {
                    "$ref": "#/components/examples/MerchantsError500Example"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BaseResponse": {
        "type": "object",
        "properties": {
          "clientContext": {
            "type": "string"
          },
          "ewSID": {
            "type": "string"
          },
          "timestampISO8601": {
            "type": "string",
            "format": "date-time"
          },
          "statusCode": {
            "type": "string"
          },
          "statusText": {
            "type": "string"
          }
        }
      },
      "MerchantAddress": {
        "type": "object",
        "description": "The Merchant’s primary address",
        "properties": {
          "line1": {
            "type": "string",
            "description": "First line of the address",
            "maxLength": 150,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&\\-_'’,.: #/]*)$"
          },
          "line2": {
            "type": "string",
            "description": "Second line of the address",
            "maxLength": 150,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&\\-_'’,.: #/]*)$"
          },
          "city": {
            "type": "string",
            "description": "City of the address",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9'’. \\-]*$"
          },
          "state": {
            "type": "string",
            "description": "State of the address",
            "maxLength": 5,
            "minLength": 5,
            "pattern": "^US-[A-Z]{2}$"
          },
          "zipCode": {
            "type": "string",
            "description": "ZIP code of the address",
            "maxLength": 5,
            "minLength": 5,
            "pattern": "^[0-9]{5}$"
          }
        },
        "required": [
          "city",
          "line1",
          "state",
          "zipCode"
        ]
      },
      "MerchantContactDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&,'’. -]*)$"
          },
          "title": {
            "type": "string",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&,'’. -]*)$"
          },
          "emailAddress": {
            "type": "string",
            "maxLength": 128,
            "minLength": 6,
            "pattern": "^(?!.*\\.{2})[A-Z0-9a-z._+-]+@(?!\\.)[A-Za-z0-9.-]+\\.[A-Za-z]{2,24}$"
          },
          "phoneNumber": {
            "type": "string",
            "maxLength": 11,
            "minLength": 10,
            "pattern": "^[0-9]*$"
          }
        }
      },
      "MerchantSubsidiaryProfile": {
        "type": "object",
        "description": "Details about subsidiary profiles to be created under the Merchant",
        "properties": {
          "profileId": {
            "type": "string",
            "description": "Merchant-defined profile identifier to distinguish between frontend applications for different brand names or use case tracking. Condition: Required for all profiles created after the first (default) profile",
            "maxLength": 50,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9_-]*$"
          },
          "domainName": {
            "type": "string",
            "description": "URL from which a profile’s checkout requests will originate",
            "maxLength": 200,
            "minLength": 0,
            "pattern": "([a-zA-Z0-9_-]{0,63}\\.)+[a-zA-Z]{2,6}(\\.[a-zA-Z]{2,6})*"
          },
          "merchantCategoryCode": {
            "type": "string",
            "description": "Merchant category code as defined by ISO 18245",
            "maxLength": 4,
            "minLength": 0,
            "pattern": "^[0-9]*$"
          }
        },
        "required": [
          "merchantCategoryCode"
        ]
      },
      "NetworkMid": {
        "type": "object",
        "properties": {
          "scheme": {
            "type": "string",
            "description": "Merchant identifier within the sponsoring Distributor’s systems",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&'’. #-]*)$"
          },
          "mid": {
            "type": "string",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9_ -]*$"
          },
          "derivedMid": {
            "type": "string",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9_ -]*$"
          }
        },
        "required": [
          "mid",
          "scheme"
        ]
      },
      "NetworkNameBaseRequest": {
        "type": "object",
        "properties": {
          "scheme": {
            "type": "string",
            "description": "Merchant identifier within the sponsoring Distributor’s systems",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&'’. #-]*)$"
          },
          "expectedAuthName": {
            "type": "string",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^([a-zA-Z0-9&'’. #-]*)$"
          }
        },
        "required": [
          "expectedAuthName",
          "scheme"
        ]
      },
      "MerchantOnboardRequest": {
        "type": "object",
        "properties": {
          "clientContext": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "legalName": {
                "type": "string",
                "description": "Merchant's legal name",
                "maxLength": 244,
                "minLength": 0,
                "pattern": "^[a-zA-Z0-9_!@#$&+\\-=~`’' \\[\\]{}<>,./\\\\~\"]*$"
              },
              "tradeName": {
                "type": "string",
                "description": "Merchant's Trade Name",
                "maxLength": 120,
                "minLength": 0,
                "pattern": "^[a-zA-Z0-9_!@#$&+\\-=~`’' \\[\\]{}<>,./\\\\~\"]*$"
              },
              "url": {
                "type": "string",
                "description": "Merchant's website URL",
                "maxLength": 2083,
                "minLength": 0,
                "pattern": "^(https?|http)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]"
              },
              "address": {
                "$ref": "#/components/schemas/MerchantAddress",
                "description": "Merchant’s primary address"
              },
              "key": {
                "$ref": "#/components/schemas/OnboardMerchantKey",
                "description": "Details about the public key that will be used to encrypt the securedPayload"
              },
              "profile": {
                "type": "array",
                "description": "Details about subsidiary profiles to be created under the Merchant",
                "items": {
                  "$ref": "#/components/schemas/MerchantSubsidiaryProfile"
                }
              },
              "customerId": {
                "type": "string",
                "description": "Merchant identifier within the sponsoring Distributor’s systems",
                "maxLength": 100,
                "minLength": 0,
                "pattern": "^[a-zA-Z0-9_-]*$"
              },
              "distributorId": {
                "type": "string",
                "description": "Distributor’s Id",
                "maxLength": 100,
                "minLength": 0,
                "pattern": "^[a-zA-Z0-9_-]*$"
              },
              "parentId": {
                "type": "string",
                "description": "Parent Id",
                "maxLength": 100,
                "minLength": 0,
                "pattern": "^([a-zA-Z0-9&'’. #-]*)$"
              },
              "onboardingEntitlement": {
                "type": "string",
                "description": "Merchant identifier within the sponsoring Distributor’s systems",
                "maxLength": 100,
                "minLength": 0,
                "pattern": "^([a-zA-Z0-9&'’. #-]*)$"
              },
              "oboIntegratorId": {
                "type": "string"
              },
              "networkNameList": {
                "type": "array",
                "description": "Merchant's Network Name",
                "items": {
                  "$ref": "#/components/schemas/NetworkNameBaseRequest"
                }
              },
              "networkMidList": {
                "type": "array",
                "description": "Merchant's network mid.",
                "items": {
                  "$ref": "#/components/schemas/NetworkMid"
                }
              },
              "merchantFLSQualification": {
                "$ref": "#/components/schemas/OnboardFlsQualification",
                "description": "Merchant FLS qualification."
              },
              "merchantBusinessContact": {
                "$ref": "#/components/schemas/MerchantContactDTO",
                "description": "Contact Information for Business contact"
              },
              "merchantProductContact": {
                "$ref": "#/components/schemas/MerchantContactDTO",
                "description": "Contact Information for Product contact"
              },
              "merchantTechnicalContact": {
                "$ref": "#/components/schemas/MerchantContactDTO",
                "description": "Contact Information for Technical contact"
              },
              "merchantMarketingContact": {
                "$ref": "#/components/schemas/MerchantContactDTO",
                "description": "Contact Information for Marketing contact"
              },
              "mobileApiAccess": {
                "type": "boolean"
              }
            },
            "required": [
              "address",
              "key",
              "legalName",
              "profile",
              "url"
            ]
          }
        }
      },
      "OnboardFlsQualification": {
        "type": "object",
        "properties": {
          "estimatedRevenueVolume": {
            "type": "string",
            "maxLength": 12,
            "minLength": 0,
            "pattern": "^[0-9]*$"
          }
        }
      },
      "OnboardMerchantKey": {
        "type": "object",
        "description": "Details about the public key that will be used to encrypt the securedPayload",
        "properties": {
          "partnerId": {
            "type": "string",
            "description": "Service Operator-generated\nidentifier for the party that will\nbe decrypting the\nsecuredPayload on the\nMerchant’s behalf\nCondition: Required if\ndata.key.certificate and\ndata.key.keyAlias are not\nprovided",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9_-]*$"
          },
          "partnerKeyAlias": {
            "type": "string",
            "description": "Existing key alias for non-Merchant party that will be decrypting the securedPayload on the Merchant’s behalf\nCondition: Required if certificate and keyAlias are not provided",
            "maxLength": 256,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9._\\-!@#$&+/\\\\=\\\"'`~]*$"
          },
          "certificate": {
            "type": "string",
            "description": "Complete .pem string (inclusive of BEGIN header and END footer) for Merchant’s public key\nUsed to encrypt securedPayload\nCondition: Required if partnerKeyAlias is not provided",
            "maxLength": 4096,
            "minLength": 0
          },
          "keyAlias": {
            "type": "string",
            "description": "Key alias for provided certificate \nCondition: Required if partnerKeyAlias is not provided",
            "maxLength": 256,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9._\\-!@#$&+/\\\\=\\\"'`~]*$"
          },
          "keyExpiry": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MerchantResponse": {
        "type": "object",
        "description": "Merchant Onboarding Response Parameters",
        "properties": {
          "clientContext": {
            "type": "string"
          },
          "ewSID": {
            "type": "string"
          },
          "timestampISO8601": {
            "type": "string",
            "format": "date-time"
          },
          "statusCode": {
            "type": "string"
          },
          "statusText": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Merchant identifier generated by Service Operator. This value is used by Merchant’s front end \nduring Initialize requests. ",
                "maxLength": 100
              }
            }
          }
        }
      }
    },
    "examples": {
      "MerchantsPostRequestExample": {
        "value": {
          "clientContext": "4a86b86c-58aa-482b-9290-5ab49b25e542DBW",
          "data": {
            "legalName": "Walmart Inc",
            "tradeName": "Walmart",
            "url": "https://www.walmart.com/",
            "address": {
              "line1": "702 SW 8th St",
              "line2": "702 SW 9th St",
              "city": "Bentonville",
              "state": "US-AR",
              "zipCode": "72712"
            },
            "key": {
              "partnerId": "partnerId",
              "partnerKeyAlias": "partner-key-alias",
              "certificate": "MIID1zCCAr+gAwIBAgIUafiwGGZbVLPTxdRHMFolrkQwD+swDQYJKoZIhvcNAQELBQAwezELMAkGA1UEBhMCVVMxDjAMBgNVBAgMBVRleGFzMQ8wDQYDVQQHDAZBdXN0aW4xETAPBgNVBAoMCFZpc2EgSW5jMQwwCgYDVQQLDANQUEQxETAPBgNVBAMMCHZpc2EuY29tMRcwFQYJKoZIhvcNAQkBFghwYXplLmNvbTAeFw0yMzEyMTIwNDI3MzhaFw0zMzEyMDkwNDI3MzhaMHsxCzAJBgNVBAYTAlVTMQ4wDAYDVQQIDAVUZXhhczEPMA0GA1UEBwwGQXVzdGluMREwDwYDVQQKDAhWaXNhIEluYzEMMAoGA1UECwwDUFBEMREwDwYDVQQDDAh2aXNhLmNvbTEXMBUGCSqGSIb3DQEJARYIcGF6ZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC/0rGYS5F3ysFmErFjbuFdoV6LaZraEG6LO/9HmjPjRZneMKfAzeTQWHcic3+STo+QgZn/7Ur5PggaFsC+iYmIflOfnNvxtkEAR0Ej5f/TBiTj/Qv4c9DmD/HhfHqfsCZ8Px+44wHnH8TOmTa2OMR60o29cXSEHZ422B/6WE7MS6u+EhmxIoqbXZaqk4kAChJAqD/Znr04KjybbduhZyjC9lAWAyzKwpCnb6/IxYXimaURFuVpPwVTMK01Ab2+DdW8u0jav1mWoEO9RHvxF1t1/Y2KyoguOupxdylP7+7IaJbnL7JJAUSt6a70x5VRfWmd+DZM99WsTKcIBsfEuDArAgMBAAGjUzBRMB0GA1UdDgQWBBQeDxNeVKkFHlSfsJOSF2aiC63ONDAfBgNVHSMEGDAWgBQeDxNeVKkFHlSfsJOSF2aiC63ONDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBVdScmIMVnTCBg7FxrHPWZ37CdUqxrHYjwLEzC4UnqUNaDySXBUumwOo+YG7Ya/VWjeR8M6r0Awty3vEoc5F9M0Xd9UXrl2RYFHFD3VkXgGbJmy8A36V7SQPEFD6wbj34kCKv/hW3uxlWm2PuNeeneKepHVcFv48glArEfHqzJMzMt7uruA1QMit1QXKKcea/taj1TM7FwjcSDCPDlQkDBpwKIC91nj6BqXzTvNiGfUsiYumNBzQ7+q9Pvn3ej3OR183w+D0oqK43pfWQkI7IZiKc0wbbyyHb1Vxy3FskjgVfgQ546XXZzpbnf06xn+GncVEf/B4DU81+Al5mYl1xT",
              "keyAlias": "walmart-key-alias"
            },
            "profile": [
              {
                "profileId": "61f379b1-a2c4-43d9-847c-da69eff36d99",
                "domainName": "walmart.com",
                "merchantCategoryCode": "0873"
              }
            ],
            "customerId": "customerId",
            "distributorId": "distributorId",
            "parentId": "parentId",
            "onboardingEntitlement": "onboardingEntitlement",
            "oboIntegratorId": "oboIntegratorId",
            "networkNameList": [
              {
                "scheme": "visa",
                "expectedAuthName": "ExpectedAuthName1"
              }
            ],
            "networkMidList": [
              {
                "scheme": "mastercard",
                "mid": "mid1"
              }
            ],
            "merchantFLSQualification": {
              "estimatedRevenueVolume": "168783441866"
            },
            "merchantBusinessContact": {
              "name": "Nick Miller",
              "title": "Business Development Executive",
              "emailAddress": "nick.miller@walmart.com",
              "phoneNumber": "72752215130"
            },
            "merchantProductContact": {
              "name": "Winston Bishop",
              "title": "Senior Product Manager",
              "emailAddress": "winston.bishop@walmart.com",
              "phoneNumber": "64225549484"
            },
            "merchantTechnicalContact": {
              "name": "Jessica Day",
              "title": "Senior Software Developer",
              "emailAddress": "jessica.day@walmart.com",
              "phoneNumber": "18431052870"
            },
            "merchantMarketingContact": {
              "name": "Winston Schmidt",
              "title": "VP of Marketing",
              "emailAddress": "winston.schmidt@walmart.com",
              "phoneNumber": "55226345439"
            },
            "mobileApiAccess": true
          }
        }
      },
      "MerchantsPost201ResponseExample": {
        "value": {
          "ewSID": "b483aa0a-39a6-4670-ab21-5e4afbe2f96b",
          "clientContext": "da5c8ccf-f7cd-492a-9dab-4f6d6a13e919",
          "statusCode": "0",
          "statusText": "Success",
          "timestampISO8601": "2025-08-11T21:17:14Z",
          "customerId": "fe0745a7-4b4a-4c1e-9168-608957206a58",
          "data": {
            "id": "X2EQCYJE28DNTRY06F5313WKaddlj1vLOusaQZNVJAaUAagYs"
          }
        }
      },
      "MerchantsError404Example": {
        "value": {
          "clientContext": "4a86b86c-58aa-482b-9290-5ab49b25e542DBW",
          "ewSID": "d3e9e952-f95d-4d39-a9b7-ff307b95fffd",
          "timestampISO8601": "2025-07-17T14:36:59.249Z",
          "statusCode": "1020",
          "statusText": "2020: An Early Warning Service error occured: [VISAERROR:404:No partner exists with Relationship with id 'moira992'. Relationship type between two partners should be OBO_PARTNER_TO_PARTNER:Resource not found:]"
        }
      },
      "MerchantsError409Example": {
        "value": {
          "clientContext": "4a86b86c-58aa-482b-9290-5ab49b25e542DBW",
          "ewSID": "d3e9e952-f95d-4d39-a9b7-ff307b95fffd",
          "timestampISO8601": "2025-07-17T14:36:59.249Z",
          "statusCode": "1020",
          "statusText": "2020: An Early Warning Service error occured: [VISAERROR:409:Domain Name already exists:Conflicting request]"
        }
      },
      "MerchantsError500Example": {
        "value": {
          "clientContext": "4a86b86c-58aa-482b-9290-5ab49b25e542DBW",
          "ewSID": "d3e9e952-f95d-4d39-a9b7-ff307b95fffd",
          "timestampISO8601": "2025-07-17T14:36:59.249Z",
          "statusCode": "1020",
          "statusText": "System Error"
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```