Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.helcim.com/v2
/customers/{customerId}
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| customerId | path | required | string | The Id of the customer |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerUpdateRequest"
}
}
}
}
PUT /customers/{customerId}
/invoices/{invoiceId}
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| invoiceId | path | required | string | The unique invoice Id |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_invoice_request"
}
}
}
}
PUT /invoices/{invoiceId}
Address
{
"type": "object",
"title": "Address",
"required": [
"name",
"postalCode",
"street1"
],
"properties": {
"city": {
"type": "string",
"example": "Calgary"
},
"name": {
"type": "string",
"example": "John Smith / Helcim",
"description": "Contact Name or Business Name"
},
"email": {
"type": "string",
"example": "john@example.com"
},
"phone": {
"type": "string",
"example": "4031231234",
"description": "10 to 15 digits phone number."
},
"country": {
"type": "string",
"example": "CAN",
"description": "3-letter abbreviation of the country(CAN, USA)"
},
"street1": {
"type": "string",
"example": "Jump Street 21"
},
"street2": {
"type": "string"
},
"province": {
"type": "string",
"example": "AB",
"description": "2 letter abbreviation of the province(AB, BC, CA). Required field if country is CAN or USA."
},
"postalCode": {
"type": "string",
"example": "H0H0H0"
}
}
}
BankAccount
{
"type": "object",
"title": "BankAccount",
"required": [
"accountCorporate",
"accountType",
"bankAccountNumber",
"city",
"companyName",
"country",
"firstName",
"lastName",
"postalCode",
"province",
"streetAddress"
],
"properties": {
"city": {
"type": "string",
"example": "Calgary"
},
"country": {
"type": "string",
"example": "CAN",
"description": "Only allow CAN - Canada, USA - United States"
},
"lastName": {
"type": "string",
"example": "Smith",
"description": "The bank account holder last name"
},
"province": {
"type": "string",
"example": "AB"
},
"firstName": {
"type": "string",
"example": "John",
"description": "The bank account holder first name"
},
"postalCode": {
"type": "string",
"example": "T2T2T2"
},
"accountType": {
"type": "string",
"example": "CHECKING",
"description": "CHECKING - Chequing, SAVINGS - Savings"
},
"companyName": {
"type": "string",
"example": "Microsoft",
"description": "The company name"
},
"bankIdNumber": {
"type": "string",
"example": "888",
"description": "Required for Canadian Bank Account Holder, the institution number - three digits - identifies your bank."
},
"padAgreement": {
"type": "boolean",
"example": true,
"description": "Customer given permission for a company or financial institution to debit a bank account when the payment is due."
},
"routingNumber": {
"type": "string",
"example": "123456789",
"description": "Required for US Bank Account Holder, a nine-digit code printed on the bottom of checks to identify the financial institution on which it was drawn."
},
"streetAddress": {
"type": "string",
"example": "440 - something"
},
"transitNumber": {
"type": "string",
"example": "55555",
"description": "Required for Canadian Bank Account Holder, the transit number - five digits - shows which branch you opened your account at."
},
"accountCorporate": {
"type": "string",
"example": "PERSONAL",
"description": "PERSONAL - Personal Bank Account, CORPORATE - Corporate Bank Account"
},
"bankAccountNumber": {
"type": "string",
"example": "999999999",
"description": "Bank account number"
}
}
}
BankAccountResponse
{
"type": "object",
"title": "BankAccount",
"properties": {
"id": {
"type": "integer",
"example": 12312,
"description": "The id of the bank account."
},
"ready": {
"type": "string",
"example": "1",
"description": "Ready status of the bank account, 1|0."
},
"address": {
"$ref": "#/components/schemas/Address"
},
"verified": {
"type": "string",
"example": "1",
"description": "Verified status of the bank account, 1|0."
},
"bankToken": {
"type": "string",
"example": "JHKJHKLKJLOHKJ876545KJBK",
"description": "The token of the bank account."
},
"customerId": {
"type": "integer",
"example": 2222,
"description": "The id of the customer owning the bank account."
},
"accountType": {
"type": "string",
"example": "CHECKING",
"description": "The type of the bank account, such as CHECKING | SAVINGS."
},
"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."
},
"bankIdNumber": {
"type": "string",
"example": "333",
"description": "The institution number of Canadian Bank Account that identifies the bank."
},
"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."
},
"routingNumber": {
"type": "string",
"example": "999999999",
"description": "The routing number of US Bank Account. Identifies the financial institution on which it was drawn."
},
"transitNumber": {
"type": "string",
"example": "55555",
"description": "The transit number of Canadian Bank Account. Shows which branch you opened your account at."
},
"accountCorporate": {
"type": "string",
"example": "PERSONAL",
"description": "The corporate type of the bank account, such as PERSONAL | CORPORATE."
},
"bankAccountNumberL4": {
"type": "string",
"example": "9999",
"description": "Last 4 digits of the bank account number."
}
}
}
BankData
{
"type": "object",
"title": "BankData",
"required": [
"bankData"
],
"properties": {
"bankData": {
"$ref": "#/components/schemas/BankData_bankData"
}
}
}
BankData_bankData
{
"oneOf": [
{
"$ref": "#/components/schemas/BankAccount"
},
{
"$ref": "#/components/schemas/BankToken"
}
]
}
BankToken
{
"type": "object",
"title": "Bank Token",
"required": [
"bankToken"
],
"properties": {
"bankToken": {
"type": "string",
"example": "HGKHJK5647698HGJJK",
"description": "The token for the bank account on file."
}
}
}
CaptureRequest
{
"type": "object",
"title": "Capture Request",
"required": [
"amount",
"ipAddress",
"preAuthTransactionId"
],
"properties": {
"amount": {
"type": "number",
"example": 100.99,
"description": "The amount to capture. Must be less or equal to the original pre-authorization amount."
},
"ecommerce": {
"type": "boolean",
"example": true,
"description": "Set to indicate that the transaction is e-commerce. When set, the Helcim Fraud Defender will provide further analysis."
},
"ipAddress": {
"type": "string",
"example": "192.168.1.1",
"description": "IP address of the customer making the transaction, used as part of fraud detection."
},
"preAuthTransactionId": {
"type": "integer",
"example": 198763,
"description": "The transaction ID of the original pre-authorization transaction."
}
}
}
Card
{
"type": "object",
"title": "Card",
"required": [
"cardCVV",
"cardExpiry",
"cardHolderName",
"cardNumber"
],
"properties": {
"cardCVV": {
"type": "string",
"example": "100",
"description": "The card CVV (3-4 digits on back of credit card)."
},
"cardExpiry": {
"type": "string",
"example": "1257",
"description": "The card expiry date, in MMYY format (total of 4 digits without spaces or slashes)."
},
"cardNumber": {
"type": "string",
"example": "5454545454545454",
"description": "The full card number (13 to 16 digits) from merchant to process \"purchase\", \"pre-auth\", and \"verify\" transactions."
}
}
}
CardBatch
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 2488717,
"description": "Id of Card batch"
},
"closed": {
"type": "boolean",
"example": true,
"description": "True if the batch is closed. Else false"
},
"netSales": {
"type": "number",
"example": 90,
"description": "Approved sales net refunds and voids"
},
"countTotal": {
"type": "number",
"example": 8,
"description": "Total number of transactions"
},
"dateClosed": {
"type": "string",
"example": "2022-11-30 14:14:53",
"description": "Date Card Batch is closed"
},
"terminalId": {
"type": "integer",
"example": 1411,
"description": "Id of associated Terminal"
},
"totalSales": {
"type": "number",
"example": 100,
"description": "Gross sales"
},
"batchNumber": {
"type": "integer",
"example": 6,
"description": "Batch Number"
},
"dateCreated": {
"type": "string",
"example": "2022-11-30 13:14:53",
"description": "Date Card batch is Created"
},
"dateUpdated": {
"type": "string",
"example": "2022-11-30 13:14:53",
"description": "Date Card batch is last updated"
},
"totalRefunds": {
"type": "number",
"example": 8.5,
"description": "Gross refunds"
},
"countApproved": {
"type": "number",
"example": 8,
"description": "Number of approved transactions"
},
"countDeclined": {
"type": "number",
"example": 0,
"description": "Number of declined transactions"
},
"totalReversed": {
"type": "number",
"example": 5,
"description": "Voided amount"
},
"totalRefundsReversed": {
"type": "number",
"example": 3.5,
"description": "Amount of voided refunds"
}
}
}
CardBatchGetAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CardBatch"
},
"description": "Array of card batches"
}
CardData
{
"type": "object",
"title": "CardData",
"required": [
"cardData"
],
"properties": {
"cardData": {
"$ref": "#/components/schemas/CardData_cardData"
}
}
}
CardData_cardData
{
"oneOf": [
{
"$ref": "#/components/schemas/Card"
},
{
"$ref": "#/components/schemas/CardToken"
}
]
}
CardResponse
{
"type": "object",
"title": "Card",
"properties": {
"id": {
"type": "integer",
"example": 161462,
"description": "The id of the card."
},
"cardCVV": {
"type": "string",
"example": "100",
"description": "The card CVV (3-4 digits on back of credit card)."
},
"cardF6L4": {
"type": "string",
"example": "5454545454",
"description": "The first-six and last-four card numbers."
},
"cardToken": {
"type": "string",
"example": "907af81acc0224e0134949",
"description": "The card token."
},
"cardExpiry": {
"type": "string",
"example": "1257",
"description": "The card expiry date, in MMYY format (total of 4 digits without spaces or slashes)."
},
"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."
}
}
}
CardTerminal
{
"type": "object",
"title": "Terminal",
"properties": {
"id": {
"type": "integer",
"example": 123,
"description": "Id of the terminal."
},
"status": {
"type": "string",
"example": "ACTIVE",
"description": "Status of Terminal. possible values are ACTIVE | INACTIVE"
},
"address": {
"$ref": "#/components/schemas/CardTerminal_address"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "Currency of terminal. possible values are CAD | USD"
},
"nickname": {
"type": "string",
"example": "Terminal 1",
"description": "Nickname of terminal"
}
}
}
CardTerminalGetAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CardTerminal"
}
}
CardTerminal_address
{
"type": "object",
"properties": {
"city": {
"type": "string",
"example": "Calgary"
},
"country": {
"type": "string",
"example": "CAN",
"description": "Abbreviation of country"
},
"street1": {
"type": "string",
"example": "Street 1"
},
"street2": {
"type": "string",
"example": "Street 2"
},
"province": {
"type": "string",
"example": "AB",
"description": "Abbreviation of province"
},
"postalCode": {
"type": "string",
"example": "H0H0H0",
"description": "Postal or zip code"
}
}
}
CardToken
{
"type": "object",
"title": "Card Token",
"required": [
"cardToken"
],
"properties": {
"cardToken": {
"type": "string",
"example": "HGKHJK5647698HGJJK",
"description": "The token for the card on file. If Customer Code is filled, The card should must be owned by a passed customer code"
}
}
}
CardTransactionCollectTransactionsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/SuccessfulPaymentResponse"
},
"description": "Array of card transactions"
}
Card_1
{
"type": "object",
"title": "Card",
"properties": {
"cardF6L4": {
"type": "string",
"example": "5454545454",
"description": "The F6L4 of card."
},
"cardToken": {
"type": "string",
"example": "a1b2c3d4e5f6",
"description": "Card token"
},
"cardHolderName": {
"type": "string",
"example": "John Smith",
"description": "The card holder name."
}
}
}
Customer
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 2488717,
"description": "Id of Customer"
},
"cards": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Card_1"
},
"description": "Array of cards stored in the vault associated with this customer."
},
"cellPhone": {
"type": "string",
"example": "908-295-4902",
"description": "Cell phone number of customer"
},
"contactName": {
"type": "string",
"example": "John Smith",
"description": "Contact Name"
},
"businessName": {
"type": "string",
"example": "Best company",
"description": "Name of the business"
},
"customerCode": {
"type": "string",
"example": "CST1200",
"description": "Customer code of the customer"
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
},
"shippingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
CustomerGetBankAccountResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/BankAccountResponse"
}
}
CustomerGetBankAccountsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/BankAccountResponse"
}
}
CustomerGetCardDetailsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CardResponse"
}
}
CustomerGetCardsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/CardResponse"
}
}
CustomerListResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Customer"
}
}
CustomerRequest
{
"type": "object",
"title": "Customer Request",
"properties": {
"cellPhone": {
"type": "string",
"example": "908-295-4902",
"description": "The cell phone number of the customer."
},
"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."
},
"customerCode": {
"type": "string",
"example": "CST1000",
"description": "The unique customer code. If blank, it will be automatically generated."
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
},
"shippingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
CustomerSetBankAccountDefaultResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/BankAccountResponse"
}
}
CustomerUpdateRequest
{
"type": "object",
"title": "Customer Update Request",
"properties": {
"cellPhone": {
"type": "string",
"example": "908-295-4902",
"description": "The cell phone number of the customer."
},
"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."
},
"customerCode": {
"type": "string",
"example": "CST1000",
"description": "The unique customer code."
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
},
"shippingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
Discount
{
"type": "object",
"title": "Discount Data",
"required": [
"amount",
"details"
],
"properties": {
"amount": {
"type": "number",
"example": 10.99,
"description": "Total Discount Amount of the Invoice"
},
"details": {
"type": "string",
"example": "DISC100",
"description": "Discount Details/Code"
}
}
}
FailedPaymentResponse
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string",
"example": "An error occured"
},
"description": "List of errors"
}
}
}
GeneralTestConnectivityToHelcimApi400Response
{
"type": "object",
"title": "Invalid Business ID",
"example": {
"errors": "invalid businessId"
}
}
GeneralTestConnectivityToHelcimApi401Response
{
"type": "object",
"title": "No credentials included",
"description": "No API token was included in the request"
}
GeneralTestConnectivityToHelcimApi403Response
{
"type": "object",
"title": "Forbidden",
"description": "Invalid API token was included in the request"
}
GeneralTestConnectivityToHelcimApiResponse
{
"type": "object",
"title": "Successful Connection Test",
"example": {
"message": "Connection Successful"
}
}
HelcimPayInitializeRequest
{
"type": "object",
"title": "Helcim Pay Initialize",
"required": [
"amount",
"currency",
"paymentType"
],
"properties": {
"amount": {
"type": "number",
"example": 100,
"description": "The amount of the transaction to be processed"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "Currency abbreviation. CAD | USD"
},
"taxAmount": {
"type": "number",
"example": 3.67,
"description": "This is used to enable level 2 processing lower rates. The value should be the dollar amount of the tax to 2 decimal places."
},
"paymentType": {
"type": "string",
"example": "purchase",
"description": "Payment Type. Valid payment types are purchase | preauth | verify"
},
"allowPartial": {
"type": "number",
"example": 1,
"description": "This is used to determine whether the partial payment UI will be displayed to the customer"
},
"customerCode": {
"type": "string",
"example": "CST1000",
"description": "This is the code of an existing customer in Helcim associated with this checkout"
},
"invoiceNumber": {
"type": "string",
"example": "INV1000",
"description": "This is the number of an existing invoice in Helcim associated with this checkout"
},
"paymentMethod": {
"type": "string",
"example": "cc-ach",
"description": "This is the payment method (credit card, ACH) that customer can use to pay the amount. cc | ach | cc-ach"
},
"hasConvenienceFee": {
"type": "number",
"example": 1,
"description": "This is used to apply the convenience fee rate to credit card transaction should customer chooses this payment method"
}
}
}
Invoice
{
"type": "object",
"title": "Invoice",
"properties": {
"amount": {
"type": "number",
"example": 100.99,
"description": "The total amount of the invoice."
},
"status": {
"type": "string",
"example": "due",
"description": "The status of the invoice, such as due | paid | completed | refunded."
},
"datePaid": {
"type": "string",
"example": "2020-01-01 00:30:50",
"description": "Date the invoice is paid."
},
"customerId": {
"type": "integer",
"example": 234,
"description": "The id of customer associated to the invoice."
},
"dateIssued": {
"type": "string",
"example": "2020-01-01 00:30:50",
"description": "Date the invoice is paid."
},
"dateCreated": {
"type": "string",
"example": "2020-01-01 00:30:50",
"description": "Date the invoice is created."
},
"dateUpdated": {
"type": "string",
"example": "2020-01-01 20:30:50",
"description": "Date the invoice is updated."
},
"convenienceFee": {
"type": "number",
"example": 100,
"description": "The total convenience fee paid for the invoice."
}
}
}
InvoiceBase
{
"type": "object",
"title": "Invoice Base",
"properties": {
"notes": {
"type": "string",
"example": "No vegetables please",
"description": "Comment to appear at the bottom of the invoice, visible to the customer."
},
"tipAmount": {
"type": "number",
"example": 0.99,
"description": "Tip amount"
},
"depositAmount": {
"type": "number",
"example": 1,
"description": "Deposit amount"
},
"invoiceNumber": {
"type": "string",
"example": "",
"description": "Invoice number of invoice to be created. Will be generated if blank"
}
}
}
InvoiceCreate
{
"type": "object",
"title": "Invoice Create",
"properties": {
"type": {
"type": "string",
"example": "INVOICE",
"description": "The type of the invoice, such as ESTIMATE | INVOICE | QUOTE | ORDER | PURCHASE_ORDER | STATEMENT | REGISTRATION | CREDIT."
},
"status": {
"type": "string",
"example": "DUE",
"description": "The status of invoice, such as DUE | SHIPPED | COMPLETED | CANCELLED"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The currency abbreviation of the invoice, such as CAD or USD. This should match currency of existing invoice."
},
"customerId": {
"type": "integer",
"example": 123123,
"description": "Unique customer Id."
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
InvoiceCreateAfterProcessing
{
"type": "object",
"title": "Invoice Create after transaction processing",
"properties": {
"tax": {
"$ref": "#/components/schemas/Tax"
},
"pickup": {
"$ref": "#/components/schemas/Pickup"
},
"discount": {
"$ref": "#/components/schemas/Discount"
},
"shipping": {
"$ref": "#/components/schemas/Shipping"
},
"lineItems": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LineItem"
},
"maxLength": 10
}
}
}
InvoiceListResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/get_invoices_200_response_inner"
}
}
InvoiceResponseBase
{
"type": "object",
"title": "Invoice Base",
"properties": {
"notes": {
"type": "string",
"example": "No vegetables please",
"description": "Comment to appear at the bottom of the invoice, visible to the customer."
},
"invoiceId": {
"type": "number",
"example": 12321,
"description": "Unique Invoice Id"
},
"tipAmount": {
"type": "number",
"example": 0.99,
"description": "Tip amount"
},
"depositAmount": {
"type": "number",
"example": 1,
"description": "Deposit amount"
},
"invoiceNumber": {
"type": "string",
"example": "INV1000",
"description": "Invoice number of invoice to be created. Will be generated if blank"
}
}
}
InvoiceUpdate
{
"type": "object",
"title": "Invoice Create",
"properties": {
"type": {
"type": "string",
"example": "INVOICE",
"description": "The type of the invoice, such as ESTIMATE | INVOICE | QUOTE | ORDER | PURCHASE_ORDER | STATEMENT | REGISTRATION | CREDIT."
},
"status": {
"type": "string",
"example": "DUE",
"description": "The status of invoice, such as DUE | SHIPPED | COMPLETED | CANCELLED"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The currency abbreviation of the invoice, such as CAD or USD. This should match currency of existing invoice."
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
LineItem
{
"type": "object",
"title": "Line Item Data",
"required": [
"description",
"price",
"quantity",
"total"
],
"properties": {
"sku": {
"type": "string",
"example": "ITM1434"
},
"price": {
"type": "number",
"example": 10.55
},
"total": {
"type": "number",
"example": 110.78,
"description": "Total = Price * Quantity"
},
"quantity": {
"type": "number",
"example": 10.5,
"description": "The quantity of the line item. Can have upto 2 decimal places"
},
"taxAmount": {
"type": "number",
"example": 0,
"description": "This will be added to Invoice's total tax amount"
},
"description": {
"type": "string",
"example": "Red Hat"
},
"discountAmount": {
"type": "number",
"example": 0,
"description": "This will be added to Invoice's total discount amount"
}
}
}
PaymentRequest
{
"type": "object",
"title": "PaymenRequest",
"required": [
"amount",
"cardData",
"currency",
"ipAddress"
],
"properties": {
"amount": {
"type": "number",
"example": 100.99,
"description": "Amount to be processed"
},
"invoice": {
"$ref": "#/components/schemas/PaymentRequest_invoice"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The currency abbreviation of the invoice, such as CAD or USD. This should match currency of existing invoice."
},
"ecommerce": {
"type": "boolean",
"example": true,
"description": "Set to indicate that the transaction is e-commerce. When set, the Helcim Fraud Defender will provide further analysis."
},
"ipAddress": {
"type": "string",
"example": "192.168.1.1",
"description": "IP address of the customer making the transaction, used as part of fraud detection."
},
"terminalId": {
"type": "integer",
"example": 3215,
"description": "For card transactions only. Id of the terminal you would want to use. Default terminal for of the currency will be used if you dont send this."
},
"customerCode": {
"type": "string",
"example": "",
"description": "Existing customer code associated with the transaction"
},
"invoiceNumber": {
"type": "string",
"example": "",
"description": "To be filled when associating transaction to existing invoice. Invoice should be associated to the same customer linked to the card"
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
PaymentRequest_invoice
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceBase"
},
{
"$ref": "#/components/schemas/InvoiceCreateAfterProcessing"
}
],
"description": "To be filled when creating new invoice to be associated to transaction. Will be linked to Customer owning the Card used"
}
PaymentReverseTransactionResponse
{
"type": "object",
"example": {},
"properties": {}
}
PaymentReverseTransactiondefaultResponse
{
"type": "object",
"example": {},
"properties": {}
}
Pickup
{
"type": "object",
"title": "Pickup Data",
"required": [
"date"
],
"properties": {
"date": {
"type": "string",
"example": "2022-01-25 13:55:55",
"description": "Pickup Date"
},
"name": {
"type": "string",
"example": "Jane Smith",
"description": "Name of the person to pickup"
}
}
}
Refund_Request
{
"type": "object",
"title": "Refund Request",
"required": [
"amount",
"ipAddress",
"originalTransactionId"
],
"properties": {
"amount": {
"type": "number",
"example": 100.99,
"description": "The amount to refund. Must be less or equal to the original purchase/capture amount."
},
"ecommerce": {
"type": "boolean",
"example": true,
"description": "Set to indicate that the transaction is e-commerce. When set, the Helcim Fraud Defender will provide further analysis."
},
"ipAddress": {
"type": "string",
"example": "192.168.1.1",
"description": "IP address of the customer making the transaction, used as part of fraud detection."
},
"originalTransactionId": {
"type": "integer",
"example": 198763,
"description": "The transaction ID of the purchase/capture transaction."
}
}
}
Refund_Request_1
{
"type": "object",
"title": "Refund Request",
"required": [
"cardTransactionId",
"ipAddress"
],
"properties": {
"ecommerce": {
"type": "boolean",
"example": true,
"description": "Set to indicate that the transaction is e-commerce. When set, the Helcim Fraud Defender will provide further analysis."
},
"ipAddress": {
"type": "string",
"example": "192.168.1.1",
"description": "IP address of the customer making the transaction, used as part of fraud detection."
},
"cardTransactionId": {
"type": "integer",
"example": 198763,
"description": "The transaction ID of the original transaction."
}
}
}
Shipping
{
"type": "object",
"title": "Shipping Data",
"required": [
"address",
"amount",
"details"
],
"properties": {
"amount": {
"type": "number",
"example": 10.99,
"description": "Total Shipping Amount of the Invoice"
},
"address": {
"$ref": "#/components/schemas/Address"
},
"details": {
"type": "string",
"example": "Canada Post 1 day shipping",
"description": "This will show up in the invoice"
}
}
}
SuccessfulAchTransactionResponse
{
"type": "object",
"title": "Ach Transaction Response",
"properties": {
"type": {
"type": "string",
"example": "WITHDRAWAL",
"description": "The type of the transaction. possible values are WITHDRAWAL | DEPOSIT | SETTLE | REVERSE | REFUND"
},
"amount": {
"type": "number",
"example": 11.99,
"description": "The amount of processed transaction"
},
"batchId": {
"type": "number",
"example": 11,
"description": "The id of associated card batch"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The abbreviation of the transaction's currency"
},
"bankToken": {
"type": "string",
"example": "-A1B2C3D4E5F6G7*",
"description": "Bank Token associated with bankAccount"
},
"statusAuth": {
"type": "string",
"example": "APPROVED",
"description": "The status of the transaction. possible values are APPROVED | DECLINED | IN_PROGRESS | CANCELLED | PENDING"
},
"dateCreated": {
"type": "string",
"example": "2020-01-01 00:00:00",
"description": "The date(Mountain Time) when the transaction is created."
},
"approvalCode": {
"type": "string",
"example": "HCMAPPRV",
"description": "Approval Code"
},
"invoiceNumber": {
"type": "string",
"example": "INV2022",
"description": "Invoice number associated to the transaction"
},
"transactionId": {
"type": "number",
"example": 10,
"description": "The transaction id"
},
"statusClearing": {
"type": "string",
"example": "OPENED",
"description": "The status of the transaction. possible values are OPENED | CLEARED | REJECTED | CONTESTED | RETURNED"
},
"bankAccountNumber": {
"type": "string",
"example": "A1B2C3D4E5F6G7",
"description": "Bank account number"
}
}
}
SuccessfulPaymentResponse
{
"type": "object",
"title": "Payment Response",
"properties": {
"type": {
"type": "string",
"example": "purchase",
"description": "The type of the transaction. possible values are purchase | preauth | verify"
},
"user": {
"type": "string",
"example": "Helcim System",
"description": "Full name of the user who processed the transaction. Default value is Helcim System"
},
"amount": {
"type": "number",
"example": 11.99,
"description": "The amount of processed transaction"
},
"status": {
"type": "string",
"example": "APPROVED",
"description": "The status of the transaction. possible values are APPROVED | DECLINED"
},
"warning": {
"type": "string",
"example": "Failed to link customer to invoice",
"description": "Warnings"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The abbreviation of the transaction's currency"
},
"cardToken": {
"type": "string",
"example": "5454HCMXTEST5454",
"description": "Card token associated to the transaction"
},
"cardNumber": {
"type": "string",
"example": "5454545454",
"description": "First-6 Last-4 numbers of the card number associated to the transaction"
},
"avsResponse": {
"type": "string",
"example": "M",
"description": "AVS Response"
},
"cardBatchId": {
"type": "number",
"example": 11,
"description": "The id of associated card batch"
},
"cvvResponse": {
"type": "string",
"example": "Y",
"description": "CVV Response"
},
"dateCreated": {
"type": "string",
"example": "2020-01-01 00:00:00",
"description": "The date(Mountain Time) when the transaction is created."
},
"approvalCode": {
"type": "string",
"example": "HCMAPPRV",
"description": "Approval Code"
},
"customerCode": {
"type": "string",
"example": "CST1010",
"description": "Customer code associated to the transaction"
},
"invoiceNumber": {
"type": "string",
"example": "INV2022",
"description": "Invoice number associated to the transaction"
},
"transactionId": {
"type": "number",
"example": 10,
"description": "The transaction id"
},
"cardHolderName": {
"type": "string",
"example": "John Smith",
"description": "Cardholdername associated to the transaction"
}
}
}
Tax
{
"type": "object",
"title": "Tax Data",
"required": [
"amount",
"details"
],
"properties": {
"amount": {
"type": "number",
"example": 5.99,
"description": "Total Tax Amount of the Invoice"
},
"details": {
"type": "string",
"example": "GST 5%",
"description": "Tax Details"
}
}
}
VerifyRequest
{
"type": "object",
"title": "Verify Request",
"required": [
"amount",
"billingAddress",
"cardData",
"currency",
"ipAddress"
],
"properties": {
"invoice": {
"$ref": "#/components/schemas/VerifyRequest_invoice"
},
"cardData": {
"$ref": "#/components/schemas/Card"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The currency abbreviation of the transaction."
},
"ecommerce": {
"type": "boolean",
"example": true,
"description": "Set to indicate that the transaction is e-commerce. When set, the Helcim Fraud Defender will provide further analysis."
},
"ipAddress": {
"type": "string",
"example": "192.168.1.1",
"description": "IP address of the customer making the transaction, used as part of fraud detection."
},
"customerCode": {
"type": "string",
"example": "",
"description": "Existing customer code associated with the transaction"
},
"invoiceNumber": {
"type": "string",
"example": "",
"description": "To be filled when associating transaction to existing invoice. Invoice should be associated to the same customer linked to the card"
},
"billingAddress": {
"$ref": "#/components/schemas/Address"
}
}
}
VerifyRequest_invoice
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceBase"
},
{
"$ref": "#/components/schemas/InvoiceCreateAfterProcessing"
}
]
}
card_terminals_request
{
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "ACTIVE",
"description": "The card terminal's status. possible values are ACTIVE | INACTIVE"
},
"currency": {
"type": "string",
"example": "CAD",
"description": "The abbreviation of card terminal's currency. Possible values are CAD | USD"
}
}
}
checkout_init_200_response
{
"type": "object",
"properties": {
"secretToken": {
"type": "string",
"description": "The secret token is used to validate the transaction response"
},
"checkoutToken": {
"type": "string",
"description": "The checkout token is used to initialize Helcim Pay"
}
}
}
checkout_init_default_response
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of errors"
}
}
}
create_invoice_200_response
{
"allOf": [
{
"type": "object"
},
{
"$ref": "#/components/schemas/InvoiceResponseBase"
},
{
"$ref": "#/components/schemas/InvoiceCreate"
},
{
"$ref": "#/components/schemas/InvoiceCreateAfterProcessing"
},
{
"$ref": "#/components/schemas/Invoice"
}
]
}
create_invoice_request
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceBase"
},
{
"$ref": "#/components/schemas/InvoiceCreate"
},
{
"$ref": "#/components/schemas/InvoiceCreateAfterProcessing"
}
]
}
get_invoice_200_response
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceResponseBase"
},
{
"$ref": "#/components/schemas/InvoiceCreate"
},
{
"$ref": "#/components/schemas/InvoiceCreateAfterProcessing"
},
{
"$ref": "#/components/schemas/Invoice"
}
]
}
get_invoices_200_response_inner
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceResponseBase"
},
{
"$ref": "#/components/schemas/Invoice"
}
]
}
purchase_request
{
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequest"
},
{
"$ref": "#/components/schemas/CardData"
}
]
}
update_invoice_request
{
"allOf": [
{
"$ref": "#/components/schemas/InvoiceBase"
},
{
"$ref": "#/components/schemas/InvoiceUpdate"
}
]
}
withdraw_request
{
"allOf": [
{
"$ref": "#/components/schemas/PaymentRequest"
},
{
"$ref": "#/components/schemas/BankData"
}
]
}