Helcim Customer API
The Customer API from Helcim — 11 operation(s) for customer.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/helcim-customer-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
description: This API covers publicly accessible merchant actions
version: 2.2.0
title: Helcim Customer API
servers:
- url: https://api.helcim.com/v2
- url: https://api.helcim.test/v2
tags:
- name: Customer
paths:
/customers:
get:
tags:
- Customer
summary: Get customers
operationId: get-customers
parameters:
- in: query
name: search
description: The search term to be used for partial matching on contactName, businessName, customerCode, city, phone and email (Only use one query field per request).
example: john
schema:
type: string
- in: query
name: customerCode
description: Existing customer code (Only use one query field per request).
example: CST1000
schema:
type: string
- in: query
name: limit
description: The limit number of customers will be returned in one request. We only allow maximum 100 objects per request. If no limit specified, the default limit will be 100 objects.
example: 25
schema:
type: integer
- in: query
name: page
description: Specifies the page number of the results you want to retrieve.
example: 1
schema:
type: integer
- in: query
name: includeCards
description: "Specifies whether to return any credit cards for retrieved customers. By default no cards are returned.\n * `yes` - return all available cards for retrieved customers.\n"
example: 'yes'
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Customer'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
post:
tags:
- Customer
summary: Create customer
operationId: create-customer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'200':
description: Successful
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}:
get:
tags:
- Customer
summary: Get customer
operationId: get-customer
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The Id of the customer
responses:
'200':
description: Successful
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
put:
tags:
- Customer
summary: Update customer
operationId: update-customer
parameters:
- in: path
name: customerId
schema:
type: string
required: true
description: The Id of the customer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerUpdateRequest'
responses:
'200':
description: Successful
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}/cards:
get:
tags:
- Customer
summary: Get customer cards
operationId: get-customer-cards
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The Id of the customer
- in: query
name: cardToken
description: The card token.
example: 907af81acc0224e0134949
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CardResponse'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}/cards/{cardId}:
get:
tags:
- Customer
summary: Get customer card
operationId: get-customer-card
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The Id of the customer
- in: path
name: cardId
schema:
type: integer
required: true
description: The Id of the card
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CardResponse'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
delete:
tags:
- Customer
summary: Delete customer card
operationId: delete-customer-card
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The ID of the customer
- in: path
name: cardId
schema:
type: integer
required: true
description: The ID of the card
responses:
'204':
description: Successfully deleted card
'404':
description: No card found
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}/cards/{cardId}/default:
patch:
tags:
- Customer
summary: Set customer card as default
operationId: set-customer-card-default
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The ID of the customer
- in: path
name: cardId
schema:
type: integer
required: true
description: The ID of the card
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Customer'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}/pads:
get:
tags:
- Customer
summary: Get all PADS for a customer.
operationId: get-pads
parameters:
- name: customerId
in: path
description: Customer ID.
required: true
schema:
type: number
responses:
'200':
description: Successfully retrieved all PADs.
content:
application/json:
schema:
$ref: '#/components/schemas/Res'
'204':
description: No PADs for a given customer.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'403':
description: User does not have valid permissions.
'500':
description: Unexpected internal error.
security:
- ApiAccessAuth: []
/customers/{customerId}/bank-accounts:
get:
tags:
- Customer
summary: Get customer bank accounts.
operationId: get-customer-bank-accounts
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The ID of the customer
- in: query
name: bankToken
description: The bank account token.
schema:
type: string
- in: query
name: verified
description: If the bank account is verified or not. Use 1 or 0.
schema:
type: number
- in: query
name: ready
description: If the bank account is verified or not. Use 1 or 0.
schema:
type: number
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankAccountResponse'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
post:
tags:
- Customer
summary: Create a bank account.
operationId: create-bank-account
parameters:
- name: customerId
in: path
description: Customer ID.
required: true
schema:
type: number
requestBody:
description: Bank information.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Req'
responses:
'201':
description: Successfully created new bank account. A bank authorization was also emailed to the customer.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Res-2'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'403':
description: User does not have valid permissions.
'500':
description: Unexpected internal error.
security:
- ApiAccessAuth: []
/customers/{customerId}/bank-accounts/request-new:
get:
tags:
- Customer
summary: Request bank account information from a customer.
operationId: request-new-bank-account
parameters:
- name: customerId
in: path
description: Customer ID.
required: true
schema:
type: number
responses:
'200':
description: Successfully sent bank account request email to customer.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'403':
description: User does not have valid permissions.
'500':
description: Unexpected internal error.
security:
- ApiAccessAuth: []
/customers/{customerId}/bank-accounts/{bankAccountId}:
get:
tags:
- Customer
summary: Get customer bank account
operationId: get-customer-bank-account
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The Id of the customer
- in: path
name: bankAccountId
schema:
type: integer
required: true
description: The Id of the bank account
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankAccountResponse'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
delete:
tags:
- Customer
summary: Delete customer bank account.
operationId: delete-customer-bank-account
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The ID of the customer
- in: path
name: bankAccountId
schema:
type: integer
required: true
description: The ID of the bank account.
responses:
'204':
description: Bank account successfully deleted.
'400':
description: Invalid request. Customer ID or bank account ID is missing or invalid.
'403':
description: User does not have valid permissions.
'404':
description: Bank account not found or has already been deleted.
'500':
description: Internal server error while deleting the bank account.
security:
- ApiAccessAuth: []
/customers/{customerId}/bank-accounts/{bankAccountId}/default:
patch:
tags:
- Customer
summary: Set customer bank account as default
operationId: set-customer-bank-account-default
parameters:
- in: path
name: customerId
schema:
type: integer
required: true
description: The Id of the customer
- in: path
name: bankAccountId
schema:
type: integer
required: true
description: The Id of the bank account
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BankAccountResponse'
default:
description: Failed
content:
application/json:
schema:
$ref: '#/components/schemas/FailedPaymentResponse'
security:
- ApiAccessAuth: []
/customers/{customerId}/bank-accounts/{bankAccountId}/pads/{padId}:
get:
tags:
- Customer
summary: Get a PAD by its ID.
operationId: get-pad
parameters:
- name: customerId
in: path
description: Customer ID.
required: true
schema:
type: number
- name: bankAccountId
in: path
description: Bank account ID.
required: true
schema:
type: number
- name: padId
in: path
description: PAD ID.
required: true
schema:
type: number
responses:
'200':
description: Successfully retrieved PAD.
content:
application/json:
schema:
$ref: '#/components/schemas/Res-3'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'403':
description: User does not have valid permissions.
'500':
description: Unexpected internal error.
security:
- ApiAccessAuth: []
put:
tags:
- Customer
summary: Update a PAD by its ID.
operationId: update-pad
parameters:
- name: customerId
in: path
description: Customer ID.
required: true
schema:
type: number
- name: bankAccountId
in: path
description: Bank account ID.
required: true
schema:
type: number
- name: padId
in: path
description: PAD ID.
required: true
schema:
type: number
requestBody:
description: Optional PAD fields to be updated.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Req-2'
responses:
'200':
description: Successfully updated PAD.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'403':
description: User does not have valid permissions.
'500':
description: Unexpected internal error.
security:
- ApiAccessAuth: []
components:
schemas:
CardResponse:
title: Card
type: object
properties:
id:
type: integer
example: 161462
description: The id of the card.
cardToken:
type: string
example: 907af81acc0224e0134949
description: The card token.
dateCreated:
type: string
example: '2025-01-30 13:35:36'
description: The date when the card is created.
dateUpdated:
type: string
example: '2025-01-30 13:35:36'
description: The date when the card last got updated.
cardHolderName:
type: string
example: John Smith
description: The cardholder name.
cardF6L4:
type: string
example: '5454545454'
description: The first-six and last-four card numbers.
cardExpiry:
type: string
example: '1257'
description: The card expiry date, in MMYY format (total of 4 digits without spaces or slashes).
cardCVV:
type: string
example: '100'
description: The card CVV (3-4 digits on back of credit card).
Customer:
type: object
properties:
id:
type: integer
example: 2488717
description: Id of Customer
customerCode:
type: string
example: CST1200
description: Customer code of the customer
businessName:
type: string
example: Best company
description: Name of the business
contactName:
type: string
example: John Smith
description: Contact Name
cellPhone:
type: string
example: 908-295-4902
description: Cell phone number of customer
billingAddress:
$ref: '#/components/schemas/Address'
shippingAddress:
$ref: '#/components/schemas/Address'
cards:
type: array
description: Array of cards stored in the vault associated with this customer.
items:
title: Card
type: object
properties:
cardHolderName:
type: string
example: John Smith
description: The card holder name.
cardF6L4:
type: string
example: 5454545454
description: The F6L4 of card.
cardToken:
type: string
example: a1b2c3d4e5f6
description: Card token
Res-3:
title: Get Pre-Authorized Debit Agreement Response Payload
type: object
properties:
pad:
$ref: '#/components/schemas/Pad'
Pad:
title: Pre-Authorized Debit Agreement
type: object
properties:
id:
type: integer
format: int64
accepted:
type: integer
format: int8
enum:
- 0
- 1
description: "Whether the PAD was accepted or not:\n * `0` - Unaccepted\n * `1` - Accepted\n"
bankAccountId:
type: integer
format: int8
customerId:
type: integer
format: int64
dateAccepted:
type: string
format: date-time
dateCreated:
type: string
format: date-time
dateEarliestDebit:
type: string
format: date-time
dateRevoked:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
ipAddress:
type: string
merchantId:
type: integer
format: int64
type:
type: integer
format: int8
enum:
- 1
- 2
description: "The type of the bank account:\n * `1` - Personal\n * `2` - Business\n"
status:
type: integer
format: int8
enum:
- 1
- 2
description: "The status of the PAD:\n * `1` - Active\n * `2` - Inactive\n"
example:
id: 238954
accepted: 1
bankAccountId: 111
customerId: 222
dateAccepted: '2023-04-23 13:30:00'
dateCreated: '2023-09-19 13:30:00'
dateEarliestDebit: '2023-10-06 13:30:00'
dateRevoked: '2023-11-17 13:30:00'
dateUpdated: '2023-08-10 13:30:00'
ipAddress: 123.456.789.0
merchantId: 333
type: 2
status: 2
Message:
title: Generic Response Payload Message
type: object
properties:
message:
type: string
CustomerRequest:
title: Customer Request
type: object
properties:
customerCode:
type: string
example: CST1000
description: The unique customer code. If blank, it will be automatically generated.
contactName:
type: string
example: John Smith
description: The primary contact name (full name) of the customer.
businessName:
type: string
example: Best Company
description: The business name of the customer. There must be either a contact name or business name present.
cellPhone:
type: string
example: 908-295-4902
description: The cell phone number of the customer.
billingAddress:
$ref: '#/components/schemas/Address'
shippingAddress:
$ref: '#/components/schemas/Address'
CustomerUpdateRequest:
title: Customer Update Request
type: object
properties:
customerCode:
type: string
example: CST1000
description: The unique customer code.
contactName:
type: string
example: John Smith
description: The primary contact name (full name) of the customer.
businessName:
type: string
example: Best Company
description: The business name of the customer. There must be either a contact name or business name present.
cellPhone:
type: string
example: 908-295-4902
description: The cell phone number of the customer.
billingAddress:
$ref: '#/components/schemas/Address'
shippingAddress:
$ref: '#/components/schemas/Address'
Req-2:
title: Update Pre-Authorized Debit Agreement
type: object
properties:
accepted:
type: integer
format: int8
enum:
- 0
- 1
description: "Whether the PAD was accepted or not:\n * `0` - Unaccepted\n * `1` - Accepted\n\nIf the PAD is set to accepted and the PAD is active, a side effect of updating the associated bank account to ready will also happen. If the PAD was set to unaccepted, it will unready the bank account.\n"
ipAddress:
type: string
type:
type: integer
format: int8
enum:
- 1
- 2
description: "The type of the bank account:\n * `1` - Personal\n * `2` - Business\n"
status:
type: integer
format: int8
enum:
- 1
- 2
description: "The status of the PAD:\n * `1` - Active\n * `2` - Inactive\n\nIf the PAD is set to active and the PAD is accepted, a side effect of updating the associated bank account to ready will also happen. If the PAD was unaccepted, it will unready the bank account. Note: there can only be 1 active PAD per bank account.\n"
example:
accepted: 1
ipAddress: 123.456.789.0
type: 2
status: 1
FailedPaymentResponse:
type: object
properties:
errors:
type: array
description: List of errors
items:
type: string
example: An error occurred
BankAccountResponse:
title: BankAccount
type: object
properties:
id:
type: integer
example: 12312
description: The id of the bank account.
customerId:
type: integer
example: 2222
description: The id of the customer owning the bank account.
dateCreated:
type: string
example: '2025-01-30 13:35:36'
description: The date when the bank account is created.
dateUpdated:
type: string
example: '2025-01-30 13:35:36'
description: The date when the bank account last got updated.
dateLastUsed:
type: string
example: '2025-01-30 13:35:36'
description: The date when the bank account last got used.
dateVerified:
type: string
example: '2025-01-30 13:35:36'
description: The date when the bank account is verified.
bankToken:
type: string
example: JHKJHKLKJLOHKJ876545KJBK
description: The token of the bank account.
accountType:
type: string
example: CHECKING
description: The type of the bank account, such as CHECKING | SAVINGS.
accountCorporate:
type: string
example: PERSONAL
description: The corporate type of the bank account, such as PERSONAL | CORPORATE.
verified:
type: string
example: 1
description: Verified status of the bank account, 1|0.
ready:
type: string
example: 1
description: Ready status of the bank account, 1|0.
bankIdNumber:
type: string
example: '333'
description: The institution number of Canadian Bank Account that identifies the bank.
transitNumber:
type: string
example: '55555'
description: The transit number of Canadian Bank Account. Shows which branch you opened your account at.
routingNumber:
type: string
example: '999999999'
description: The routing number of US Bank Account. Identifies the financial institution on which it was drawn.
bankAccountNumberL4:
type: string
example: '9999'
description: Last 4 digits of the bank account number.
address:
$ref: '#/components/schemas/Address'
Req:
title: Create Bank Account Request Payload
type: object
required:
- accountCorporate
- accountType
- bankAccountNumber
- city
- countryAlpha2
- postalCode
- provinceAlpha2
- streetAddress
properties:
accountCorporate:
type: integer
format: int8
enum:
- 1
- 2
description: "The bank account type:\n * `1` - Personal\n * `2` - Corporate\n"
accountType:
type: integer
format: int8
enum:
- 1
- 2
description: "The bank account type:\n * `1` - Checking\n * `2` - Savings\n"
bankAccountNumber:
type: string
description: 7-12 digits for Canadian bank accounts and 8-12 for US bank accounts.
bankFinancialNumber:
type: string
description: This 3 digit number is needed for Canadian bank accounts.
bankRoutingNumber:
type: string
description: This 9 digit number is needed for US bank accounts.
bankTransitNumber:
type: string
description: This 5 digit number is needed for Canadian bank accounts.
city:
type: string
countryAlpha2:
type: string
description: Country name in ISO2 format, e.g "CA", "US"
firstName:
type: string
description: Either first and last name or company name need to be specified.
lastName:
type: string
description: Either first and last name or company name need to be specified.
companyName:
type: string
description: Either first and last name or company name need to be specified.
postalCode:
type: string
provinceAlpha2:
type: string
description: Province/State name in ISO2 format, e.g "AB", "ON"
streetAddress:
type: string
example:
accountCorporate: 1
accountType: 2
bankAccountNumber: '123456789'
bankFinancialNumber: '123'
bankTransitNumber: '12345'
city: Calgary
countryAlpha2: CA
firstName: John
lastName: Doe
postalCode: T2P5E9
provinceAlpha2: AB
streetAddress: 440 2 Ave SW
Address:
title: Address
type: object
required:
- name
- street1
- postalCode
properties:
name:
type: string
description: 'The recipient''s name or business name for this address.
'
example: John Smith / Helcim
street1:
type: string
description: 'The primary street address.
'
example: 21 Jump Street
street2:
type: string
description: 'Additional address details, such as unit or suite number.
'
example: Suite 400
city:
type: string
description: 'The city for this address.
'
example: Calgary
province:
type: string
description: 'The two-letter province or state code (e.g., AB, BC, CA). Required if the country is CAN or USA.
'
example: AB
country:
type: string
description: 'The three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code (e.g., CAN, USA).
'
example: CAN
postalCode:
type: string
description: 'The postal or ZIP code for this address.
'
example: H0H0H0
phone:
type: string
description: 'Contact phone number (10 to 15 digits).
'
example: 4031231234
email:
type: string
description: 'Contact email address for this address.
'
example: john@example.com
Res-2:
type: object
properties:
message:
type: string
example: 'Successfully created new bank account with ID #12345. A bank authorization email was also emailed to customer@helcim.com.'
bankAccount:
type: object
properties:
id:
type: integer
format: int64
example:
id: 12345
Res:
title: Get All Pre-Authorized Debit Agreement Response Payload
type: object
properties:
pads:
type: array
items:
$ref: '#/components/schemas/Pad'
securitySchemes:
ApiAccessAuth:
description: API Token with required permissions
type: apiKey
in: header
name: api-token