Skip to content
Payments docs are in beta — the OpenAPI contract is the source of truth.API reference
VortexPayments
Esc
↑↓navigate↵open⌘Jpreview

Create a sub-merchant account

POST/v1/merchant-accounts
Authorization
AuthorizationBearer token · headerrequired
Public API key bearer token.
Query parameters
environmentstringrequired
merchantAccountIdstringrequired
Header parameters
Idempotency-Keystring
Required for production-safe retries on mutating routes. Reusing a key with a different request body returns 409.
min length 1
Request body
requiredapplication/json
environmentstringrequired
Allowed:sandboxproduction
externalMerchantRefstring
Your stable reference for this merchant. Optional; generated when omitted.
displayNamestringrequired
legalEntityTypestringrequired
countrystringrequired
merchantModestringrequired
defaultCurrencystringrequired
tenantIdstring
Must match the caller's organization when present; rejected otherwise.
platformMerchantAccountIdstring
Connect: provision this account as a linked sub-merchant under an operator-granted platform account the caller controls (sandbox only in v1). The account is created in a fresh claimable org; the response carries `claimUrl`/`claimExpiresAt` for handing ownership to the sub-merchant.
doingBusinessAsstring
businessPhonestring
businessTaxIdstring
phonestring
taxIdstring
emailstring
firstNamestring
lastNamestring
mccstring
urlstring
maxTransactionAmountnumber
achMaxTransactionAmountnumber
annualCardVolumenumber
principalPercentageOwnershipnumber
hasAcceptedCreditCardsPreviouslyboolean
dateOfBirthMerchantProfileDate
Show properties
daynumberrequired
monthnumberrequired
yearnumberrequired
incorporationDateMerchantProfileDate
Show properties
daynumberrequired
monthnumberrequired
yearnumberrequired
businessAddressMerchantAddress
Show properties
line1stringrequired
line2string
citystringrequired
regionstring
postalCodestringrequired
countrystringrequired
personalAddressMerchantAddress
Show properties
line1stringrequired
line2string
citystringrequired
regionstring
postalCodestringrequired
countrystringrequired
settlementBankAccountMerchantSettlementBankAccount
Show properties
namestringrequired
accountNumberstringrequired
bankCodestringrequired
accountTypestringrequired
attemptValidationCheckboolean
associatedIdentitiesMerchantAssociatedIdentity[]
Show properties
Array of MerchantAssociatedIdentity
identityRolesstring[]required
relationTypestring
firstNamestring
lastNamestring
titlestring
emailstring
phonestring
taxIdstring
principalPercentageOwnershipnumber
dateOfBirthMerchantProfileDate
Show properties
daynumberrequired
monthnumberrequired
yearnumberrequired
personalAddressMerchantAddress
Show properties
line1stringrequired
line2string
citystringrequired
regionstring
postalCodestringrequired
countrystringrequired
underwritingMerchantUnderwritingData
Show properties
annualAchVolumenumber
averageAchTransferAmountnumber
averageCardTransferAmountnumber
businessDescriptionstring
creditCheckAllowedboolean
creditCheckIpAddressstring
creditCheckTimestampstring
creditCheckUserAgentstring
refundPolicystring
cardVolumeDistributionobject
Show properties
cardPresentPercentagenumber
ecommercePercentagenumber
mailOrderTelephoneOrderPercentagenumber
volumeDistributionByBusinessTypeobject
Show properties
businessToConsumerVolumePercentagenumber
consumerToConsumerVolumePercentagenumber
otherVolumePercentagenumber
metadataobject
Responses
200Success
dataobjectrequired
requestIdstringrequired
400Bad request, including malformed JSON
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
401Missing or invalid API key
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
409Conflict, including idempotency body drift
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
422Validation failed
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
429API key rate limit exceeded
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
defaultError
errorobjectrequired
Show properties
codestringrequired
Allowed:bad_requestunauthorizedforbiddennot_foundconflictrate_limitedvalidation_failurenot_implementedinternal_error
messagestringrequired
requestIdstring
docsUrlstring
Deep link to the errors guide section for this code.
detailsobject
Request
curl -X POST "https://api.vortex.nyc/v1/merchant-accounts?environment=string&merchantAccountId=string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "sandbox",
  "externalMerchantRef": "string",
  "displayName": "string",
  "legalEntityType": "string",
  "country": "string",
  "merchantMode": "string",
  "defaultCurrency": "string",
  "tenantId": "string",
  "platformMerchantAccountId": "string",
  "doingBusinessAs": "string",
  "businessPhone": "string",
  "businessTaxId": "string",
  "phone": "string",
  "taxId": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "mcc": "string",
  "url": "string",
  "maxTransactionAmount": 0,
  "achMaxTransactionAmount": 0,
  "annualCardVolume": 0,
  "principalPercentageOwnership": 0,
  "hasAcceptedCreditCardsPreviously": true,
  "dateOfBirth": {
    "day": 0,
    "month": 0,
    "year": 0
  },
  "incorporationDate": {
    "day": 0,
    "month": 0,
    "year": 0
  },
  "businessAddress": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "personalAddress": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "settlementBankAccount": {
    "name": "string",
    "accountNumber": "string",
    "bankCode": "string",
    "accountType": "string",
    "attemptValidationCheck": true
  },
  "associatedIdentities": [
    {
      "identityRoles": [
        "string"
      ],
      "relationType": "string",
      "firstName": "string",
      "lastName": "string",
      "title": "string",
      "email": "string",
      "phone": "string",
      "taxId": "string",
      "principalPercentageOwnership": 0,
      "dateOfBirth": {
        "day": 0,
        "month": 0,
        "year": 0
      },
      "personalAddress": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postalCode": "string",
        "country": "string"
      }
    }
  ],
  "underwriting": {
    "annualAchVolume": 0,
    "averageAchTransferAmount": 0,
    "averageCardTransferAmount": 0,
    "businessDescription": "string",
    "creditCheckAllowed": true,
    "creditCheckIpAddress": "string",
    "creditCheckTimestamp": "string",
    "creditCheckUserAgent": "string",
    "refundPolicy": "string",
    "cardVolumeDistribution": {
      "cardPresentPercentage": 0,
      "ecommercePercentage": 0,
      "mailOrderTelephoneOrderPercentage": 0
    },
    "volumeDistributionByBusinessType": {
      "businessToConsumerVolumePercentage": 0,
      "consumerToConsumerVolumePercentage": 0,
      "otherVolumePercentage": 0
    }
  },
  "metadata": {}
}'
Response
{
  "data": {},
  "requestId": "string"
}