SchemaBoardingMerchant Platforms

Create processing account

View as Markdown
Use this method to add an additional processing account to a merchant platform. To add a processing account to a merchant platform, you need the merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the [Create Merchant Platform](https://docs.payroc.com/api/schema/boarding/merchant-platforms/create) method. **Note**: If you don't have the merchantPlatformId, use our [List Merchant Platforms](https://docs.payroc.com/api/schema/boarding/merchant-platforms/list) method to search for the merchant platform. In the request, include the following information: - Business details, including its business type, time zone, and address. - Owners' details, including their contact details. - Funding, pricing, and processing information, including its pricing model and funding accounts. - Additional forms that you need us to send to the merchant, for example, attestations and questionnaires. When you send a successful request, we review the information about the processing account. After we complete our review and approve the processing account, we assign a processingAccountId, which you need to perform follow-on actions. **Note**: You can subscribe to our processingAccount.status.changed event to get notifications when we update the status of a processing account. For more information about how to subscribe to events, go to [Events List](https://docs.payroc.com/knowledge/events/events-list).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

merchantPlatformIdstringRequired
Unique identifier of the merchant platform that we sent to you when you created the merchant platform.

Headers

Idempotency-KeystringRequiredformat: "uuid"
Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency).

Request

This endpoint expects an object.
doingBusinessAsstringRequired<=100 characters
Trading name of the business.
ownerslist of objectsRequired

Collection of individuals that are responsible for a processing account. When you create a processing account, you must indicate at least one owner as either of the following:

  • Control prong - An individual who has a significant equity stake in the business and can make decisions for the processing account. You can add only one control prong to a processing account.
  • Authorized signatory - An individual who doesn’t have an equity stake in the business but can make decisions for the processing account.
merchandiseOrServiceSoldstringRequired<=125 characters
Description of the services or merchandise sold by the business.
businessStartDatedateRequired

Date that the business was established. The format of the value is YYYY-MM-DD.

timezoneenumRequired
Time zone for the processing account.
addressobjectRequired
Polymorphic object that contains address information for the processing account.
contactMethodslist of objectsRequired

Array of polymorphic objects, which contain contact information.

Note: You must provide an email address.

The value of the type parameter determines which variant you should use:

  • email - Email address
  • phone - Phone number
  • mobile - Mobile number
  • fax - Fax number.
processingobjectRequired
Object that contains information about how we process transactions for the account.
fundingobjectRequired
Object that contains information about the funding schedule of the processing account.
pricingobjectRequired

Polymorphic object that contains pricing information for the processing account.

The value of the type parameter determines which variant you should use:

  • intent - Use a pricing agreement template.
  • agreement - Create a new pricing agreement.
signatureobjectRequired

Polymorphic object that contains information about how we captured the owner’s signature.

The value of the type parameter determines which variant you should use:

  • requestedViaDirectLink - Request signature using a link.
  • requestedViaEmail - Request signature by email.
websitestringOptional<=128 characters
Website address of the business.
businessTypeenumOptional
Type of business.
categoryCodeintegerOptional

Merchant Category Code (MCC) for the type of business.

processorenumOptionalDefaults to tsys

Processor that authorizes and settles transactions for the processing account.

Note: We recommend that you include a value for the processor parameter and not rely on the default value.

contactslist of objectsOptional
Array of contact objects.
addendumslist of objectsOptional

Array of polymorphic addendumEntry objects that indicate the additional forms that we should send with the Merchant Processing Agreement (MPA).

The value of the type parameter determines which variant you should use:

  • installmentPaymentsV1 - Send this form if the merchant offers installment payments, loans, or leases.
  • moneyServicesV1 - Send this form if the merchant offers money services, for example, traveler’s checks.
  • telehealthV1 - Send this form if the merchant provides telehealth services.
  • firearmsV1 - Send this form if the merchant sells firearms.
  • pharmacyCnpComplianceV1 - Send this form if the merchant is a pharmacy that accepts card-not-present (CNP) transactions.
  • cbdV1 - Send this form if the merchant sells any of the following products:
    • CBD products
    • Synthetic THC or Cannabis
    • HHC
    • Kratom
    • Tianeptine
    • Delta 8/9/10/0 THC products
  • tobaccoCnpV1 - Send this form if the merchant sells tobacco products and accepts CNP transactions.
  • donationsV1 - Send this form if the merchant accepts donations.
  • cloverMerchantProcessingAmendmentV1 - Send this form if the merchant requires Clover equipment.
metadatamap from strings to stringsOptional

Object that you can send to include custom data in the request. For more information about how to use metadata, go to Metadata.

Response headers

locationstringOptional
URI reference to the resource.

Response

Successful request. We created the processing account.
doingBusinessAsstring<=100 characters
Trading name of the business.
ownerslist of objectsRead-only
Object that contains information about the owners of the business.
merchandiseOrServiceSoldstring<=125 characters
Description of the services or merchandise sold by the business.
timezoneenum
Time zone for the processing account.
addressobject
Polymorphic object that contains address information for the processing account.
contactMethodslist of objects

Array of polymorphic objects, which contain contact information.

Note: You must provide an email address.

The value of the type parameter determines which variant you should use:

  • email - Email address
  • phone - Phone number
  • mobile - Mobile number
  • fax - Fax number
processingobject
Object that contains information about how we process transactions for the account.
fundingobject
Object that contains funding information for the processing account, including funding schedules, funding fees, and details of funding accounts.
pricingobject
Object that HATEOAS links to the pricing information that we apply to the processing account.
signatureobject

Polymorphic object that contains information about how we captured the owner’s signature.

The value of the type parameter determines which variant you should use:

  • requestedViaDirectLink - Request signature using a link.
  • requestedViaEmail - Request signature by email.
addendumslist of objectsRead-only

Array of polymorphic addendumEntry objects. Each object indicates the additional form that we sent to the merchant with the Merchant Processing Agreement (MPA).

The value of the type parameter determines which variant you should use.

processingAccountIdstringOptionalRead-only
Unique identifier of the processing account.
createdDatedatetimeOptionalRead-only
Date and time that we received your request to create the processing account in our system.
lastModifiedDatedatetimeOptionalRead-only
Date and time that the processing account was last modified.
statusenumOptionalRead-only

Status of the processing account.

  • entered - We have received information about the account, but we have not yet reviewed it.
  • pending - We have reviewed the information about the account, but we have not yet approved it.
  • approved - We have approved the account for processing transactions and funding.
  • subjectTo - We have approved the account, but we are waiting on further information.
  • dormant - Account is closed for a period.
  • nonProcessing - We have approved the account, but the merchant has not yet run a transaction.
  • rejected - We rejected the application for the processing account.
  • terminated - Processing account is closed.
  • cancelled - Merchant withdrew the application for the processing account.
    Note: You can subscribe to our processingAccount.status.changed event to get notifications when we change the status of a processing account. For more information about how to subscribe to events, go to Event Subscriptions.
websitestringOptional<=128 characters
Website address of the business.
businessTypeenumOptional
Type of business.
categoryCodeintegerOptional

Merchant Category Code (MCC) for the type of business.

processorenumOptionalDefaults to tsys

Processor that authorizes and settles transactions for the processing account.

Note: We recommend that you include a value for the processor parameter and not rely on the default value.

businessStartDatedateOptional

Date that the business was established. The format of the value is YYYY-MM-DD.

contactslist of objectsOptionalRead-only
Array of contact objects.
metadatamap from strings to stringsOptional

Object that you can send to include custom data in the request. For more information about how to use metadata, go to Metadata.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
500
Internal Server Error