Skip to main content

Creating Applications for Merchant Accounts

If your business has hundreds of billers, franchisees, or sub-merchants, this API streamlines the process of submitting their information for underwriting. After the application has been approved, they will be automatically configured with all the payment and payout methods specified in that application.

Requirements

In order to use this API, you must have completed the initial application process and have been set up by your PayPal Account Manager, with login credentials to the Braintree control panel.

Creating an Application

To create a merchant account application, you will specify all relevant business information for underwriting and configuration options for each payment method you will accept.

Mutation

mutation ExampleApplication($input: CreateMerchantAccountApplicationInput!) {
  createMerchantAccountApplication(input: $input) {
    clientMutationId
    merchantAccountApplication {
      id
      status
    }
  }
}

Variables

{
  "input": {
    "uniqueIdentifier": "<unique-id-in-your-system>",
    "clientMutationId": "<optional-relay-spec-mutation-id>",
    "business": {
      "type": "PRIVATE_CORPORATION",
      "dbaName": "DinoSoar",
      "legalName": "Cretaceous Logistics",
      "federalTaxId": "201234567",
      "idType": "EMPLOYER_IDENTIFICATION_NUMBER",
      "idIssuer": "USA",
      "stateOfRegistration": "CA",
      "merchantCategoryCode": "5978",
      "startDate": "2001-01-23",
      "logoUrl": "http://example.com/logo.png",
      "email": "payments@example.com",
      "address": {
        "streetAddress": "123 Tarpit Lane",
        "locality": "La Brea",
        "region": "CA",
        "postalCode": "92821",
        "countryCode": "USA"
      },
      "phoneCountryCode": 1,
      "phoneNumber": "234567890",
      "phoneType": "BUSINESS",
      "website": "https://example.com",
      "annualVolume": 1000000,
      "averageTransactionSize": 10,
      "largestTransactionSize": 1000,
      "arrears": false,
      "percentageOneTime": 0,
      "deliveryDays": 0,
      "refundPolicy": "NO_REFUND_OR_EXCHANGE",
      "subscriptions": {
        "percentMonthly": 0,
        "percentQuarterly": 0,
        "percentSemiAnnual": 0,
        "percentAnnual": 0,
      },
    },
    "owners": [
      {
        "role": "BENEFICIAL_OWNER",
        "ownershipPercentage": 100,
        "firstName": "Tyrone",
        "lastName": "Rexford",
        "position": "PARTNER",
        "email": "t.rexford@example.com",
        "address": {
          "streetAddress": "987 Tarpit Lane",
          "locality": "La Brea",
          "region": "CA",
          "postalCode": "92821",
          "countryCode": "USA"
        },
        "addressType": "HOME",
        "dateOfBirth": "1970-12-31",
        "phoneCountryCode": 1,
        "phoneNumber": "987654321",
        "phoneType": "MOBILE",
        "idType": "SOCIAL_SECURITY_NUMBER",
        "idNumber": "012345678",
        "idIssuer": "USA"
      }
    ],
    "americanExpressRelationship": {
      "serviceEstablishmentNumber": "5021011432"
    },
    "salesAccount": {
      "accountNumber": "0123456789",
      "routingNumber": "021000021",
      "accountType": "CORPORATION",
      "transferType": "BANK_ACCOUNT_USA",
      "accountPurpose": "CHECKING",
      "entityType": "COMPANY"
    },
    "discountProgramRegistration": {
      "registrationType": "UTIL_RATE",
      "registrationIdentifier": "123456789",
      "numberOfCustomers": 1000,
      "acceptanceChannel": ["WEB"],
      "utilityType": ["TRASH", "GAS", "ELECTRIC"],
      "loanPayday": false,
      "loanFee": false
    },
    "achConfiguration": {
      "companyId": "1123456789",
      "entry": "Cretaceous Logistics",
      "reinitiation": "true"
    }
  }
}

Response

{
  "data": {
    "createMerchantAccountApplication": {
      "clientMutationId": "<value-passed-in-mutation>",
      "merchantAccountApplication": {
        "id": "<new-UUID>",
        "status": "PROCESSING"
    }
  }
}

Error Handling

General API error documentation

{
  "data": {},
  "errors": [
    {
      "message": "Business type must be valid. See data dictionary.",
      "locations": [{
        "line": 12,
        "column": 34
      }],
      "path": ["createMerchantAccountApplication"],
      "extensions": {
        "errorType": "user_error",
        "errorClass": "VALIDATION",
        "legacyCode": "abc_123",
        "inputPath": ["input", "business", "type"]
      }
    }
  ],
  "extensions": {
    "requestId": "<your-mutation-id>"
  }
}