Connected account registrations

Using our connected account registration process and webhook events, we can link merchants who sign up through your partner registration URL link with your systems identifier for that merchant. This way we can communicate the outcome of that referral registration and send the merchants api-token to store securely in your system for processing if the merchant account is approved.

Partner registration URL

After registering to become a partner through our partner portal, the Helcim Partnership team will provide you with your partner-token.

When you refer merchants to Helcim, you will send them a unique URL for their registration. This registration URL contains two additional parameters and should look something like this.

https://hub.helcim.com/signup/register?pt=<partner_token>&cid=<connected_account_identifier>

• The "pt" parameter value for <partner_token>, should be the token provided to you by our Partnership team, and will be the same for every registration.
• The "cid" parameter value for <connected_account_identifier>, should be the unique value you use to identify the referred merchant in your system, and will change for every unique registration.

When we receive a registration in our system through your registration link using these two URL parameters, the referred merchant becomes a "Connected Account" and the webhook notification process is enabled.

Through this webhook process we will notify you of the outcome of the referrals application, as well as their api-token if approved, so that you can process on that merchants behalf through your integration.

📘

Connected Account Webhooks

Review our documentation for Connected Account Webhook Events, so that you are automatically notified when a referred merchant is approved and receive their api-token in a secure manner.

Pre-filled registrations

If you're collecting business information from the merchants you refer to Helcim when they sign up for your platform, then you can pre-fill the partner registration form and send that data to Helcim using a single API call.

Pre-filling the registration form reduces the amount of effort required for a potential connected account to sign up for Helcim's services, by presenting users with a signup application that is pre-filled with information previously provided to partners.

Information in the form is not locked and the person registering for the account can remove or amend the values of any pre-filed field, so long a the validation and submission requirements of the registration form are met.

POST requests with connected account details should be sent to https://api.helcim.com/v2/applications/prefill. All requests must contain the partners api-token in the header of the request, with the connectedAccountId and the primary email address the merchant will be registering with in the body of the request.

📘

Your partner api-token will be provided through a secure link emailed to a person of your choosing.

The connectedAccountId should be generated by the partner, however they would like to keep track of their connected accounts. At this point in time, Helcim accepts a connectedAccountId made up of letters, numbers, underscores, and hyphens, to a 255 character limit.

Request fields

We currently support the pre-filling of the following fields of signup.

Request example

// Example pre-filled registration POST request

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: Bearer {your_partner_api_token}
  },
  body: JSON.stringify({
    "connectedAccountId": "partnerIdValue1000",
    "emailAddress": "[email protected]",
    "businessOperatingName": "Example Corp",
    "businessLegalName": "Example Corporation",
    "businessYearRegistered": 1989,
    "businessType": "INCORPORATED",
    "businessPhoneNumber": "(123)-123-1234",
    "businessWebsite": "www.example.com",
    "processingCurrency": "USD",
    "businessAddress": {
      "street1": "1st Street",
      "street2": "Apt #1",
      "city": "New York",
      "province": "NY",
      "country": "USA",
      "postalCode": "10009"
    }
  })
};

fetch('https://api.helcim.com/v2/applications/prefill', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Successful API response

The Pre-filled Registration endpoint will respond to your requests with one of the following:

For valid requests that have been successfully processed, the HTTP response code will be 201 Created and the response payload will be the following:

{
  "message": "Successfully saved registration information"
}

After a you receive a successful response to your request to pre-fill connected account information, you can then direct potential connected accounts to sign up through your partner registration URL.

• https://hub.helcim.com/signup/register?ptnr=<partner_token>&cid=<connected_account_identifier>

Errors and error handling

If there are validation issues, the response will contain information on which fields were invalid and the acceptable formats for those fields. For example, for a request payload that contains an invalid email address and business registration year, the HTTP response code will be 400 Bad Request and the response payload will be the following:

{
  "timestamp": "2024-11-01T16:24:31+00:00",
  "status": "error",
  "errors": {
    "ERR_INVALID_REQUEST": [
      {
        "code": "ERR_INVALID_REQUEST",
        "source": "emailAddress",
        "data": "[][email protected]",
        "message": "emailAddress is a required field and must be in the format: [email protected]"
      }
    ]
  }
}

In the case of failed authentication, the HTTP response code will be 401 Unauthorized and the response payload will be the following:

{
  "timestamp": "2024-11-01T16:24:31+00:00",
  "status": "error",
  "errors": {
    "ERR_UNAUTHORIZED": [
      {
        "code": "ERR_UNAUTHORIZED",
        "message": "You are not authorized to access this resource."
      }
    ]
  }
}

For any server issues that result in the request not being processed successfully, the HTTP response code will be 500 Internal Server Error and the response payload will be the following:

{
  "timestamp": "2024-11-01T16:24:31+00:00",
  "status": "error",
  "errors": {
    "ERR_INTERNAL": [
      {
        "code": "ERR_INTERNAL",
        "message": "An internal error has occurred"
      }
    ]
  }
}

Co-branded registrations

Through Helcim's co-branded registrations, you can reduce the friction for referred merchants signing up for their Helcim account, but keeping a consistent brand presence through their registration for services with Helcim.

In order to have your partner registration URL co-branded, please provide your Helcim Partner Specialist with the following.

• Logo and brand guideline documentation, including the HEX code for your primary brand colour.

Once we receive these assets, Helcim will configure your partner registration URL to match your branding in addition to ours. Once your co-branded page is ready to go, the Partnerships Team will notify you.

In order for co-branded registrations to be displayed, please ensure that your partner-token URL parameter in your partner registration URL is correct for all merchants referred to Helcim for processing. This is what our system is looking for to present the co-branded version of the registration.

https://hub.helcim.com/signup/register?pt=<partner_token>&cid=<abc123def456>

👍

Example of co-branded registration

https://hub.helcim.com/signup/register?pt=b03d48c80dc813