Skip to main content

Creating Applications for Merchant Accounts

AVAILABILITY

The Merchant Application API is only available for select merchants at this time.

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. You'll also need to work with your Account Manager to configure and set up all the features you require.

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. For more context on the information you need to provide, see the Data Dictionary.

Mutation

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

Variables

{
  "input": {
    "uniqueIdentifier": "<unique-id-in-your-system>",
    "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": "7733441458",
      "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": "7733441458",
        "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"
    },
    "discountProgramRegistration": {
      "registrationType": "UTIL_RATE",
      "registrationIdentifier": "123456789",
      "numberOfCustomers": 1000,
      "acceptanceChannel": ["WEB"],
      "utilityType": ["TRASH", "GAS", "ELECTRIC"],
      "loanPayday": false,
      "loanFee": false
    },
    "achConfiguration": {
      "companyName": "Cretaceous LGX",
      "entry": "Creat LGX",
      "reinitiation": "true",
      "softDescriptor": "DinoSoar"
    }
  }
}

Response

{
  "data": {
    "createMerchantAccountApplication": {
      "merchantAccountApplication": {
        "id": "<new-UUID>",
        "legacyId": "<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": "12345",
        "inputPath": ["input", "business", "type"]
      }
    }
  ],
  "extensions": {
    "requestId": "<your-mutation-id>"
  }
}