{"openapi":"3.0.0","info":{"description":"This API covers publicly accessible merchant actions","version":"2.2.0","title":"The Helcim API"},"servers":[{"url":"https://api.helcim.com/v2"},{"url":"https://api.helcim.test/v2"}],"tags":[{"name":"General"}],"paths":{"/connection-test":{"get":{"tags":["General"],"summary":"Tests connectivity to the Helcim API","operationId":"connectionTest","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"title":"Successful Connection Test","example":{"message":"Connection Successful"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"title":"Invalid Business ID","example":{"errors":"invalid businessId"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"title":"No credentials included","description":"No API token was included in the request"}}}},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"title":"Forbidden","description":"Invalid API token was included in the request"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/purchase":{"post":{"tags":["Payment"],"summary":"Process a Purchase Transaction","operationId":"purchase","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentRequest"},{"$ref":"#/components/schemas/CardData"}]},"example":{"ipAddress":"192.168.1.1","ecommerce":true,"terminalId":3215,"currency":"CAD","amount":100.99,"customerCode":"","invoiceNumber":"","cardData":{"cardNumber":"5454545454545454","cardExpiry":"1257","cardCVV":"100","cardHolderName":"John Doe"},"billingAddress":{"name":"John Smith / Helcim","street1":"21 Jump Street","street2":"Suite 400","city":"Calgary","province":"AB","country":"CAN","postalCode":"H0H0H0","phone":"4031231234","email":"john@example.com"}}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/preauth":{"post":{"tags":["Payment"],"summary":"Process a Preauth Transaction","operationId":"preauth","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PreauthRequest"},{"$ref":"#/components/schemas/CardData"}]},"example":{"ipAddress":"192.168.1.1","ecommerce":true,"terminalId":3215,"currency":"CAD","amount":100.99,"customerCode":"","invoiceNumber":"","cardData":{"cardNumber":"5454545454545454","cardExpiry":"1257","cardCVV":"100","cardHolderName":"John Doe"},"billingAddress":{"name":"John Smith / Helcim","street1":"21 Jump Street","street2":"Suite 400","city":"Calgary","province":"AB","country":"CAN","postalCode":"H0H0H0","phone":"4031231234","email":"john@example.com"}}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/capture":{"post":{"tags":["Payment"],"summary":"Process a Capture Transaction","operationId":"capture","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/verify":{"post":{"tags":["Payment"],"summary":"Process a Verify Transaction","operationId":"verify","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/refund":{"post":{"tags":["Payment"],"summary":"Process a Refund Transaction","operationId":"refund","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"title":"Refund Request","type":"object","required":["originalTransactionId","amount","ipAddress"],"properties":{"originalTransactionId":{"type":"integer","example":198763,"description":"The transaction ID of the purchase/capture transaction.  In-person debit transactions cannot be refunded through payment API"},"amount":{"type":"number","example":100.99,"description":"The amount to refund. Must be less or equal to the original purchase/capture amount."},"ipAddress":{"type":"string","example":"192.168.1.1","description":"IP address of the customer making the transaction, used as part of fraud detection."},"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."}}}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/reverse":{"post":{"tags":["Payment"],"summary":"Process a Reverse Transaction","operationId":"reverse","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"title":"Refund Request","type":"object","required":["cardTransactionId","ipAddress"],"properties":{"cardTransactionId":{"type":"integer","example":198763,"description":"The transaction ID of the original transaction."},"ipAddress":{"type":"string","example":"192.168.1.1","description":"IP address of the customer making the transaction, used as part of fraud detection."},"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."}}}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/payment/withdraw":{"post":{"deprecated":true,"tags":["Payment"],"summary":"Process a Withdraw Transaction","operationId":"withdraw","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentRequest"},{"$ref":"#/components/schemas/BankData"}]}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulAchTransactionResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/card-batches":{"get":{"tags":["Card Batch"],"summary":"Get Card Batches","operationId":"get-card-batches","parameters":[{"in":"query","name":"batchNumber","description":"The number of the batch to retrieve. Note that this is the batch number, not batch ID.","example":18900,"schema":{"type":"number"}},{"in":"query","name":"terminalId","description":"The terminalId of the requested batch","example":180000,"schema":{"type":"number"}},{"in":"query","name":"collect-stats","description":"Includes transaction statistics for the batch","example":true,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"array","description":"Array of card batches","items":{"$ref":"#/components/schemas/CardBatch"}}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/card-batches/{cardBatchId}":{"get":{"tags":["Card Batch"],"summary":"Get Card Batch","operationId":"get-card-batch","parameters":[{"in":"path","name":"cardBatchId","schema":{"type":"integer"},"required":true,"description":"The Card Batch Id of the Card Batch you want to get"},{"in":"query","name":"collect-stats","description":"Includes transaction statistics for the batch","example":true,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardBatch"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/card-batches/{cardBatchId}/settle":{"post":{"tags":["Card Batch"],"summary":"Settles an Open Card Batch","operationId":"settle-card-batch","parameters":[{"in":"path","name":"cardBatchId","schema":{"type":"integer"},"required":true,"description":"The Card Batch Id of the Card Batch you want to settle"}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardBatch"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/card-transactions":{"get":{"tags":["Card Transaction"],"summary":"Collects up to 1000 Card Transactions","operationId":"get-card-transactions","parameters":[{"in":"query","name":"dateFrom","description":"Filters transactions created from 2020-01-01 (Mountain Time)","example":"2020-01-01","schema":{"type":"string"}},{"in":"query","name":"dateTo","description":"Filters transactions created until 2021-01-01 (Mountain Time)","example":"2021-01-01","schema":{"type":"string"}},{"in":"query","name":"search","description":"Searches amount, card number(F6L4 only), cardholder name, & approval codes","example":500,"schema":{"type":"string"}},{"in":"query","name":"customerCode","description":"The code of the customer associated with the transaction","example":"CST1000","schema":{"type":"string"}},{"in":"query","name":"invoiceNumber","description":"The number of the invoice associated with the transaction","example":"INV1000","schema":{"type":"string"}},{"in":"query","name":"cardToken","description":"The token of the card associated with the transaction","example":"5454JK97UU1F5454","schema":{"type":"string"}},{"in":"query","name":"cardBatchId","description":"The id of the batch associated with the transaction","example":3,"schema":{"type":"integer"}},{"in":"query","name":"limit","description":"The limit number of transactions will be returned in one request. We only allow maximum 1000 objects per request. If no limit specified, the default limit will be 1000 objects.","example":100,"schema":{"type":"integer"}},{"in":"query","name":"page","description":"Specifies the page number of the results you want to retrieve.","example":1,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"array","description":"Array of card transactions","items":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/card-transactions/{cardTransactionId}":{"get":{"tags":["Card Transaction"],"summary":"Get Card Transaction by id","operationId":"get-card-transaction","parameters":[{"in":"path","name":"cardTransactionId","schema":{"type":"integer"},"required":true,"description":"The Card Transaction Id of the Card Transaction you want to get"}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessfulPaymentResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/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":[]}]}},"/invoices":{"post":{"tags":["Invoice"],"summary":"Create invoice","operationId":"create-invoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpsertRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]},"get":{"tags":["Invoice"],"summary":"Get invoices","operationId":"get-invoices","parameters":[{"in":"query","name":"page","description":"Page number for paginated results. Defaults to the first page if omitted.\n","example":1,"schema":{"type":"integer","minimum":1}},{"in":"query","name":"dateStart","description":"Filter invoices created on or after this date or date-time. Format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. If time is omitted, `00:00:00` is assumed. If `dateEnd` is provided, it must not be earlier than `dateStart`.\n","example":"2020-01-01","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"dateEnd","description":"Filter invoices created on or before this date or date-time. Format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. If time is omitted, `23:59:59` is assumed. If `dateStart` is provided, `dateEnd` must not be earlier than `dateStart`.\n","example":"2021-01-01","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"invoiceNumber","description":"Filter invoices by the exact invoice number. Matches exactly (case-insensitive). If no match exists, no invoices are returned.\n","example":"INV1000","schema":{"type":"string"}},{"in":"query","name":"customerId","description":"Filter invoices by customer ID.\n","example":12345,"schema":{"type":"string"}},{"in":"query","name":"status","description":"Filter invoices by status.\n","example":"PAID","schema":{"type":"string","enum":["CANCELLED","DUE","PAID","SHIPPED","COMPLETED","REFUNDED","APP","IN_PROGRESS","OVERDUE","FOR_APPROVAL","APPROVED"]}},{"in":"query","name":"type","description":"Filter invoices by type.\n","example":"INVOICE","schema":{"type":"string","enum":["ESTIMATE","QUOTE","ORDER","PURCHASE_ORDER","INVOICE","STATEMENT","REGISTRATION","CREDIT"]}},{"in":"query","name":"currency","description":"Filter invoices by currency code.\n","example":"USD","schema":{"type":"string","enum":["CAD","USD"]}},{"in":"query","name":"withConvenienceFee","description":"Include the convenience fee for each invoice.  If `1`, the convenience fee is included in the response.  If `0` or omitted, the convenience fee is set to 0.\n","example":1,"schema":{"type":"integer","enum":[0,1]}},{"in":"query","name":"withOrderFields","description":"Include custom field values for each invoice. If `1`, the `orderFields` array for each invoice is populated. If `0` or omitted, `orderFields` is always an empty array.\n","example":1,"schema":{"type":"integer","enum":[0,1]}},{"in":"query","name":"convenienceFeeEnabled","description":"Filter invoices by whether the convenience fee is enabled.  If `1`, return all invoices with the convenience fee enabled. If `0`, return all invoices with the convenience fee disabled.  If omitted, no filter is applied.\n","example":1,"schema":{"type":"integer","enum":[0,1]}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceResponse"}}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/invoices/{invoiceId}":{"get":{"tags":["Invoice"],"summary":"Get invoice","operationId":"get-invoice","parameters":[{"in":"path","name":"invoiceId","schema":{"type":"string"},"required":true,"description":"The unique ID of the invoice to retrieve."}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]},"put":{"tags":["Invoice"],"summary":"Update invoice","operationId":"update-invoice","parameters":[{"in":"path","name":"invoiceId","schema":{"type":"string"},"required":true,"description":"The unique invoice Id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpsertRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/ach/withdraw":{"put":{"tags":["ACH Payment"],"summary":"Process an ACH withdraw.","operationId":"ach-withdraw","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Req-3"}}}},"responses":{"200":{"description":"An ACH withdrawal was successfully processed. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Res-4"}}}},"400":{"description":"Invalid request. Likely caused by malformed content in request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/ach/transactions":{"get":{"tags":["ACH Payment"],"summary":"Collects all ACH transactions.","operationId":"get-many-ach-transactions","parameters":[{"in":"query","name":"page","description":"Page number for paginated results.","example":1,"schema":{"type":"integer","minimum":1}},{"in":"query","name":"limit","description":"The number of transactions that will be returned in one request. We only allow maximum 125 objects per request.  If no limit specified, the default limit will be 125 objects.\n","example":50,"schema":{"type":"integer","maximum":125}},{"in":"query","name":"startDate","description":"Filter transactions created on or after this date. Format: `YYYY-MM-DD`. If `endDate` is provided, it must not be earlier than `startDate`.\n","example":"2020-01-01","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","description":"Filter transactions created on or before this date. Format: `YYYY-MM-DD`. If `startDate` is provided, `endDate` must not be earlier than `startDate`.\n","example":"2021-01-01","schema":{"type":"string","format":"date"}},{"in":"query","name":"amountMin","description":"Filter transactions by minimum amount. If `amountMax` is provided, `amountMin` must not be greater than `amountMax`.\n","example":150,"schema":{"type":"number","format":"float"}},{"in":"query","name":"amountMax","description":"Filter transactions by maximum amount. If `amountMin` is provided, `amountMax` must not be less than `amountMin`.\n","example":200,"schema":{"type":"number","format":"float"}},{"in":"query","name":"statusAuth","description":"Filter transactions by auth status.","example":"APPROVED,PENDING","schema":{"type":"array","items":{"type":"string","enum":["APPROVED","DECLINED","IN_PROGRESS","PENDING","CANCELLED"]}}},{"in":"query","name":"statusClearing","description":"Filter transactions by clearing status.","example":"REJECTED,CONTESTED","schema":{"type":"array","items":{"type":"string","enum":["OPENED","CLEARED","REJECTED","CONTESTED","RETURNED"]}}},{"in":"query","name":"users","description":"Filter transactions by users.","example":"1234,5678,8271","schema":{"type":"array","items":{"type":"integer"}}},{"in":"query","name":"search","description":"Searches id, bankAccountL4l4, order id, batch id, contact name and business name.\n","example":"Joe","schema":{"type":"string"}}],"responses":{"200":{"description":"All ACH transactions.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TransactionEft"}}}}},"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":[]}]}},"/ach/transactions/{transactionId}":{"get":{"tags":["ACH Payment"],"summary":"Retrieves a single ACH transaction.","operationId":"get-ach-transaction-by-id","parameters":[{"name":"transactionId","in":"path","schema":{"type":"integer"},"required":true,"description":"The ID of the ACH transaction."}],"responses":{"200":{"description":"An ACH transaction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEft"}}}},"400":{"description":"Invalid request. Likely due to using an invalid ACH transaction ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/ach/transactions/{transactionId}/refund":{"put":{"tags":["ACH Payment"],"summary":"Refund an ACH transaction.","operationId":"ach-refund","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","description":"The ID of the ACH transaction to refund.","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Req-4"}}}},"responses":{"200":{"description":"An ACH refund was successfully processed. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Res-5"}}}},"400":{"description":"Invalid request. Likely caused by malformed content in request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/ach/transactions/{transactionId}/void":{"put":{"tags":["ACH Payment"],"summary":"Void an ACH transaction.","operationId":"ach-void","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","description":"The ID of the ACH transaction to void.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The ACH transaction was successfully voided. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Res-6"}}}},"400":{"description":"Invalid request. Likely caused by providing an ACH transaction ID referencing a transaction that is not eligible for voiding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/ach/transactions/{transactionId}/cancel":{"patch":{"tags":["ACH Payment"],"summary":"Cancel a pending ACH transaction.","operationId":"ach-cancel","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","description":"The ID of the ACH transaction to cancel.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The pending ACH transaction was successfully cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Res-7"}}}},"400":{"description":"Invalid request. Likely due to the ACH transaction not being pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/ach/batches":{"get":{"tags":["ACH Payment"],"summary":"Collects all ACH batches.","operationId":"get-many-ach-batches","responses":{"200":{"description":"All ACH Batches.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AchBatch"}}}}},"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":[]}]}},"/ach/batches/{batchId}/settle":{"put":{"tags":["ACH Payment"],"summary":"Settle an ACH batch.","operationId":"ach-batch-settle","parameters":[{"in":"header","name":"idempotency-key","description":"A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"batchId","in":"path","schema":{"type":"integer"},"required":true,"description":"The ID of the ACH batch."}],"responses":{"200":{"description":"The ACH batch was successfully settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Res-8"}}}},"400":{"description":"Invalid request. Likely caused by the batch not being eligible for settling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"403":{"description":"User does not have valid permissions."},"500":{"description":"Unexpected internal error."}},"security":[{"ApiAccessAuth":[]}]}},"/card-terminals":{"get":{"tags":["Card Terminal"],"summary":"Get card terminals","operationId":"card-terminals","parameters":[{"name":"currency","in":"query","schema":{"type":"string","example":"CAD"},"description":"The abbreviation of the card terminal's currency. Possible values are CAD | USD"},{"name":"status","in":"query","schema":{"type":"string","example":"ACTIVE"},"description":"The card terminal's status. possible values are ACTIVE | INACTIVE"}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CardTerminal"}}}}},"default":{"description":"Failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedPaymentResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/devices":{"get":{"tags":["Device"],"summary":"Get Devices","operationId":"get-devices","description":"This operation requires the provided API key to have General permission set to 'Read' or higher, and Settings permission set to 'Read' or higher.\n","parameters":[{"name":"code","in":"query","description":"Four Digit Alphanumeric Code. Can be a partial match.","example":"XY7Z","schema":{"type":"string","maxLength":4}},{"name":"limit","in":"query","description":"Specifies the maximum number of devices to be returned in one request.\nThe maximum allowed limit is 100 objects per request.\nIf not specified, the default limit is 100 objects.\n","example":10,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"offset","in":"query","description":"Specifies the offset of the results you want to retrieve.\nNote: offset and page cannot be used simultaneously.\n","example":100,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"page","in":"query","description":"Specifies the page number of the results you want to retrieve.\nNote: offset and page cannot be used simultaneously.\n","example":2,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}}}},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"404":{"description":"Devices Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/devices/{code}":{"get":{"tags":["Device"],"summary":"Get Device Information","operationId":"get-device","description":"This operation requires the provided API key to have General permission set to 'Read' or higher, and Settings permission set to 'Read' or higher.\n","parameters":[{"name":"code","in":"path","required":true,"description":"Four Digit Alphanumeric Code","schema":{"type":"string","maxLength":4}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"404":{"description":"Device Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/devices/{code}/payment/purchase":{"post":{"tags":["Device"],"summary":"Start A Purchase","operationId":"start-purchase","description":"This operation requires the provided API key to have Processing permission set to 'PositiveTransaction' or higher.\n","parameters":[{"name":"code","in":"path","required":true,"description":"Four Digit Alphanumeric Code.","schema":{"type":"string","maxLength":4}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest-2"}}}},"responses":{"202":{"description":"Accepted"},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"404":{"description":"Device Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"409":{"description":"Device Not Listening","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/devices/{code}/payment/refund":{"post":{"tags":["Device"],"summary":"Start A Refund","operationId":"start-refund","description":"This operation requires the provided API key to have Processing permission set to 'Admin'.\n","parameters":[{"name":"code","in":"path","required":true,"description":"Four Digit Alphanumeric Code.","schema":{"type":"string","maxLength":4}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"202":{"description":"Accepted"},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"404":{"description":"Device Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"409":{"description":"Device Not Listening","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}},"/devices/{code}/ping":{"get":{"tags":["Device"],"summary":"Send a Ping Event to a Device","operationId":"ping-device","parameters":[{"name":"code","in":"path","required":true,"description":"Four Digit Alphanumeric Code","schema":{"type":"string","maxLength":4}}],"responses":{"202":{"description":"Accepted"},"403":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"404":{"description":"Device Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"409":{"description":"Device Not Listening","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailedResponse"}}}}},"security":[{"ApiAccessAuth":[]}]}}},"components":{"securitySchemes":{"ApiAccessAuth":{"description":"API Token with required permissions","type":"apiKey","in":"header","name":"api-token"}},"schemas":{"Card":{"title":"Card","type":"object","required":["cardNumber","cardExpiry","cardCVV","cardHolderName"],"properties":{"cardNumber":{"type":"string","example":5454545454545454,"description":"The full card number (13 to 16 digits) from merchant to process \"purchase\", \"pre-auth\", and \"verify\" transactions."},"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)."},"cardHolderName":{"type":"string","example":"John Doe","description":"The name of the card holder as it appears on the card."}}},"Address":{"title":"Address","type":"object","required":["name","street1","postalCode"],"properties":{"name":{"type":"string","description":"The recipient's name or business name for this address.\n","example":"John Smith / Helcim"},"street1":{"type":"string","description":"The primary street address.\n","example":"21 Jump Street"},"street2":{"type":"string","description":"Additional address details, such as unit or suite number.\n","example":"Suite 400"},"city":{"type":"string","description":"The city for this address.\n","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.\n","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).\n","example":"CAN"},"postalCode":{"type":"string","description":"The postal or ZIP code for this address.\n","example":"H0H0H0"},"phone":{"type":"string","description":"Contact phone number (10 to 15 digits).\n","example":4031231234},"email":{"type":"string","description":"Contact email address for this address.\n","example":"john@example.com"}}},"PaymentRequestBase":{"title":"PaymentRequestBase","type":"object","required":["amount","currency","cardData","ipAddress"],"properties":{"ipAddress":{"type":"string","example":"192.168.1.1","description":"IP address of the customer making the transaction, used as part of fraud detection."},"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."},"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."},"currency":{"type":"string","example":"CAD","description":"The currency abbreviation of the invoice, such as CAD or USD. This should match currency of existing invoice."},"amount":{"type":"number","example":100.99,"description":"Amount to be processed"},"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"},"cardData":{"$ref":"#/components/schemas/Card"},"billingAddress":{"$ref":"#/components/schemas/Address"}}},"InvoiceBase":{"title":"Invoice Base","type":"object","properties":{"invoiceNumber":{"type":"string","example":"","description":"Invoice number of invoice to be created. Will be generated if blank"},"notes":{"type":"string","example":"No vegetables please","description":"Comment to appear at the bottom of the invoice, visible to the customer."}}},"InvoiceWithTip":{"title":"InvoiceWithTip","allOf":[{"$ref":"#/components/schemas/InvoiceBase"},{"type":"object","properties":{"tipAmount":{"type":"number","example":0.99,"description":"Tip amount"}}}]},"Shipping":{"title":"Shipping Data","type":"object","required":["amount","details","address"],"properties":{"amount":{"type":"number","format":"float","description":"The total shipping amount for the invoice.\n","example":10.99},"details":{"type":"string","description":"A description of the shipping method. This information appears on the invoice.\n","example":"Canada Post 1-day shipping"},"address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"The destination shipping address for this invoice.\n"}}},"Pickup":{"title":"Pickup Data","type":"object","required":["date"],"properties":{"date":{"type":"string","description":"The scheduled pickup date and time in the format: `YYYY-MM-DD HH:MM:SS`.\n","example":"2022-01-25 13:55:55"},"name":{"type":"string","readOnly":true,"description":"Read-only. Derived from the linked customer's contact name (empty when no customer is linked to the invoice). A `name` supplied in a create or update request is ignored — only `date` is writable. To change the displayed pickup name, update the linked customer's contact name.\n","example":"Jane Smith"}}},"Tax":{"title":"Tax Data","type":"object","required":["amount","details"],"properties":{"amount":{"type":"number","format":"float","description":"The total tax amount applied at the invoice level.  This does not include item-level taxes.\n","example":5.99},"details":{"type":"string","description":"A description of the tax or tax breakdown.\n","example":"GST 5%"}}},"Discount":{"title":"Discount Data","type":"object","required":["amount","details"],"properties":{"amount":{"type":"number","format":"float","description":"The total discount amount applied at the invoice level.  This does not include item-level discounts.\n","example":10.99},"details":{"type":"string","description":"A description or code identifying the discount.\n","example":"DISC100"}}},"LineItem":{"title":"Line Item Data","type":"object","required":["description","quantity","price"],"properties":{"description":{"type":"string","description":"A short description of the product or service.\n","example":"Red Hat"},"quantity":{"type":"number","format":"float","description":"The quantity of the line item. Can have up to 2 decimal places.\n","example":10.5},"price":{"type":"number","format":"float","description":"The unit price for a single quantity of this line item, before tax or discounts.\n","example":10.55},"taxAmount":{"type":"number","format":"float","description":"The tax amount for this line item.\n","example":0},"discountAmount":{"type":"number","format":"float","description":"The discount amount applied to this line item.\n","example":0},"sku":{"type":"string","description":"The stock keeping unit (SKU) code for this product (or service).\n","example":"ITM1434"}}},"InvoiceCreateAfterProcessing":{"title":"Invoice Create after transaction processing","type":"object","properties":{"shipping":{"$ref":"#/components/schemas/Shipping"},"pickup":{"$ref":"#/components/schemas/Pickup"},"tax":{"$ref":"#/components/schemas/Tax"},"discount":{"$ref":"#/components/schemas/Discount"},"lineItems":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/LineItem"}}}},"PaymentRequest":{"title":"PaymentRequest","allOf":[{"$ref":"#/components/schemas/PaymentRequestBase"},{"type":"object","properties":{"invoice":{"allOf":[{"$ref":"#/components/schemas/InvoiceWithTip"},{"$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"}}}]},"CardToken":{"title":"Card Token","type":"object","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"}}},"CardData":{"title":"CardData","type":"object","required":["cardData"],"properties":{"cardData":{"oneOf":[{"$ref":"#/components/schemas/Card"},{"$ref":"#/components/schemas/CardToken"}]}}},"FailedPaymentResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of errors","items":{"type":"string","example":"An error occurred"}}}},"SuccessfulPaymentResponse":{"title":"Payment Response","type":"object","properties":{"transactionId":{"type":"number","example":10,"description":"The transaction id"},"cardBatchId":{"type":"number","example":11,"description":"The id of associated card batch"},"dateCreated":{"type":"string","example":"2020-01-01 00:00:00","description":"The date(Mountain Time) when the transaction is created."},"status":{"type":"string","example":"APPROVED","description":"The status of the transaction. possible values are APPROVED | DECLINED"},"user":{"type":"string","example":"Helcim System","description":"Full name of the user who processed the transaction. Default value is Helcim System"},"type":{"type":"string","example":"purchase","description":"The type of the transaction. possible values are purchase | preauth | verify"},"amount":{"type":"number","example":11.99,"description":"The amount of processed transaction"},"currency":{"type":"string","example":"CAD","description":"The abbreviation of the transaction's currency"},"avsResponse":{"type":"string","example":"M","description":"AVS Response"},"cvvResponse":{"type":"string","example":"Y","description":"CVV Response"},"cardType":{"type":"string","example":"Visa","description":"Abbreviated card issuer name\n  * `VI` - Visa\n  * `MC` - MasterCard\n  * `AX` - American Express\n  * `DI` - Discover\n  * `DCI` - Diners Club\n  * `JCB` - JCB\n  * `UP` - China Union Pay\n  * `MR` - Maestro\n  * `AF` - AFFN\n  * `AO` - Alaska Option\n  * `CU` - Credit Union 24\n  * `EB` - EBT Network\n  * `EX` - Accel\n  * `IL` - Interlink\n  * `NT` - Nets\n  * `NY` - NYCE\n  * `PS` - Pulse\n  * `ST` - Star\n  * `SZ` - Shazam\n  * `AT` - ATH\n  * `IN` - Interac\n  * `DB` - Debit\n"},"approvalCode":{"type":"string","example":"HCMAPPRV","description":"Approval Code"},"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"},"cardHolderName":{"type":"string","example":"John Smith","description":"Cardholdername associated to the transaction"},"customerCode":{"type":"string","example":"CST1010","description":"Customer code associated to the transaction"},"invoiceNumber":{"type":"string","example":"INV2022","description":"Invoice number associated to the transaction"},"warning":{"type":"string","example":"Failed to link customer to invoice","description":"Warnings"}}},"PreauthRequest":{"title":"PreauthRequest","allOf":[{"$ref":"#/components/schemas/PaymentRequestBase"},{"type":"object","properties":{"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"}}}]},"CaptureRequest":{"title":"Capture Request","type":"object","required":["preAuthTransactionId","amount","ipAddress"],"properties":{"preAuthTransactionId":{"type":"integer","example":198763,"description":"The transaction ID of the original pre-authorization transaction."},"amount":{"type":"number","example":100.99,"description":"The amount to capture. Must be less or equal to the original pre-authorization amount."},"ipAddress":{"type":"string","example":"192.168.1.1","description":"IP address of the customer making the transaction, used as part of fraud detection."},"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."}}},"VerifyRequest":{"title":"Verify Request","type":"object","required":["amount","currency","cardData","billingAddress","ipAddress"],"properties":{"ipAddress":{"type":"string","example":"192.168.1.1","description":"IP address of the customer making the transaction, used as part of fraud detection."},"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."},"currency":{"type":"string","example":"CAD","description":"The currency abbreviation of the transaction."},"amount":{"type":"number","example":100,"description":"Amount to be verified"},"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"},"invoice":{"allOf":[{"$ref":"#/components/schemas/InvoiceBase"},{"$ref":"#/components/schemas/InvoiceCreateAfterProcessing"}]},"cardData":{"$ref":"#/components/schemas/Card"},"billingAddress":{"$ref":"#/components/schemas/Address"}}},"BankAccount":{"title":"BankAccount","type":"object","required":["firstName","lastName","companyName","bankAccountNumber","accountType","accountCorporate","streetAddress","city","country","province","postalCode"],"properties":{"firstName":{"type":"string","example":"John","description":"The bank account holder first name"},"lastName":{"type":"string","example":"Smith","description":"The bank account holder last name"},"companyName":{"type":"string","example":"Microsoft","description":"The company name"},"bankAccountNumber":{"type":"string","example":999999999,"description":"Bank account number"},"accountType":{"type":"string","example":"CHECKING","description":"CHECKING - Chequing, SAVINGS - Savings"},"accountCorporate":{"type":"string","example":"PERSONAL","description":"PERSONAL - Personal Bank Account, CORPORATE - Corporate Bank Account"},"bankIdNumber":{"type":"string","example":888,"description":"Required for Canadian Bank Account Holder, the institution number - three digits - identifies your bank."},"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."},"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"},"city":{"type":"string","example":"Calgary"},"country":{"type":"string","example":"CAN","description":"Only allow CAN - Canada, USA - United States"},"province":{"type":"string","example":"AB"},"postalCode":{"type":"string","example":"T2T2T2"},"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."}}},"BankToken":{"title":"Bank Token","type":"object","required":["bankToken"],"properties":{"bankToken":{"type":"string","example":"HGKHJK5647698HGJJK","description":"The token for the bank account on file."}}},"BankData":{"title":"BankData","type":"object","required":["bankData"],"properties":{"bankData":{"oneOf":[{"$ref":"#/components/schemas/BankAccount"},{"$ref":"#/components/schemas/BankToken"}]}}},"SuccessfulAchTransactionResponse":{"title":"Ach Transaction Response","type":"object","properties":{"transactionId":{"type":"number","example":10,"description":"The transaction id"},"batchId":{"type":"number","example":11,"description":"The id of associated card batch"},"dateCreated":{"type":"string","example":"2020-01-01 00:00:00","description":"The date(Mountain Time) when the transaction is created."},"statusAuth":{"type":"string","example":"APPROVED","description":"The status of the transaction. possible values are APPROVED | DECLINED | IN_PROGRESS | CANCELLED | PENDING"},"statusClearing":{"type":"string","example":"OPENED","description":"The status of the transaction. possible values are OPENED | CLEARED | REJECTED | CONTESTED | RETURNED"},"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"},"currency":{"type":"string","example":"CAD","description":"The abbreviation of the transaction's currency"},"approvalCode":{"type":"string","example":"HCMAPPRV","description":"Approval Code"},"bankAccountNumber":{"type":"string","example":"A1B2C3D4E5F6G7","description":"Bank account number"},"bankToken":{"type":"string","example":"-A1B2C3D4E5F6G7*","description":"Bank Token associated with bankAccount"},"invoiceNumber":{"type":"string","example":"INV2022","description":"Invoice number associated to the transaction"}}},"CardBatch":{"type":"object","properties":{"id":{"type":"integer","example":2488717,"description":"Id of Card batch"},"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"},"dateClosed":{"type":"string","example":"2022-11-30 14:14:53","description":"Date Card Batch is closed"},"closed":{"type":"boolean","example":true,"description":"True if the batch is closed. Else false"},"terminalId":{"type":"integer","example":1411,"description":"Id of associated Terminal"},"batchNumber":{"type":"integer","example":6,"description":"Batch Number"},"netSales":{"type":"number","example":90,"description":"Approved sales net refunds and voids"},"totalSales":{"type":"number","example":100,"description":"Gross sales"},"totalRefunds":{"type":"number","example":8.5,"description":"Gross refunds"},"totalReversed":{"type":"number","example":5,"description":"Voided amount"},"totalRefundsReversed":{"type":"number","example":3.5,"description":"Amount of voided refunds"},"countTotal":{"type":"number","example":8,"description":"Total number of transactions"},"countApproved":{"type":"number","example":8,"description":"Number of approved transactions"},"countDeclined":{"type":"number","example":0,"description":"Number of declined transactions"}}},"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"}}}}}},"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"}}},"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)."}}},"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}},"Res":{"title":"Get All Pre-Authorized Debit Agreement Response Payload","type":"object","properties":{"pads":{"type":"array","items":{"$ref":"#/components/schemas/Pad"}}}},"Message":{"title":"Generic Response Payload Message","type":"object","properties":{"message":{"type":"string"}}},"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"}},"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-3":{"title":"Get Pre-Authorized Debit Agreement Response Payload","type":"object","properties":{"pad":{"$ref":"#/components/schemas/Pad"}}},"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}},"OrderField":{"title":"Order Field Data","type":"object","properties":{"displayName":{"type":"string","example":"Table Number"},"value":{"type":"string","example":"44B"}}},"InvoiceResponse":{"title":"InvoiceResponse","type":"object","properties":{"invoiceId":{"type":"integer","description":"Unique ID of the invoice.","example":28658838},"invoiceNumber":{"type":"string","description":"Invoice number. Generated if not provided during creation.","example":"INV1000"},"token":{"type":"string","description":"A system generated unique token to reference the invoice with. can be used to view the invoice online.\n","example":"4e71b0b71b032e8bd95097"},"type":{"type":"string","description":"The type of the invoice.  Possible values include: ESTIMATE, INVOICE, QUOTE, ORDER, PURCHASE_ORDER, STATEMENT, REGISTRATION, CREDIT.\n","example":"INVOICE"},"status":{"type":"string","description":"The current status of the invoice. Possible values include: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, APP, IN_PROGRESS, OVERDUE, FOR_APPROVAL, APPROVED.\n","example":"DUE"},"currency":{"type":"string","description":"The three-letter ISO 4217 currency code for this invoice. Possible values include: CAD, USD.\n","example":"CAD"},"customerId":{"type":"integer","description":"ID of the customer associated with this invoice. Will be 0 if no customer is associated with the invoice.\n","example":15301549},"billingAddress":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"The billing address for this invoice."},"shipping":{"allOf":[{"$ref":"#/components/schemas/Shipping"}],"description":"Shipping details for this invoice."},"pickup":{"allOf":[{"$ref":"#/components/schemas/Pickup"}],"description":"Pickup details for this invoice."},"tax":{"allOf":[{"$ref":"#/components/schemas/Tax"}],"description":"Tax details for this invoice."},"discount":{"allOf":[{"$ref":"#/components/schemas/Discount"}],"description":"Discount details for this invoice."},"lineItems":{"type":"array","description":"List of line items included in this invoice.\n","items":{"$ref":"#/components/schemas/LineItem"}},"dateCreated":{"type":"string","format":"date-time","description":"The date and time when the invoice was created.","example":"2025-06-20 13:05:03"},"dateUpdated":{"type":"string","format":"date-time","description":"The date and time when the invoice was last updated.","example":"2025-06-20 13:05:03"},"datePaid":{"type":"string","format":"date-time","description":"The date and time when the invoice was paid, if applicable.","example":"0000-00-00 00:00:00"},"dateIssued":{"type":"string","format":"date-time","description":"The date and time when the invoice was issued.","example":"2025-06-20 13:05:03"},"amount":{"type":"number","format":"float","description":"The total amount of the invoice.","example":127.48},"amountPaid":{"type":"number","format":"float","description":"The total amount that has been paid towards this invoice.","example":0},"amountDue":{"type":"number","format":"float","description":"The remaining balance due for this invoice.","example":127.48},"tipAmount":{"type":"number","format":"float","description":"The tip amount applied to this invoice.","example":0.99},"depositAmount":{"type":"number","format":"float","description":"The deposit for items on the invoice, e.g bottle fees.","example":0},"convenienceFee":{"type":"number","format":"float","description":"The total convenience fee applied to this invoice.","example":0},"convenienceFeeEnabled":{"type":"boolean","description":"Indicates whether a convenience fee was enabled for this invoice.","example":false},"surchargingFee":{"type":"number","format":"float","description":"The total surcharging fee applied to this invoice.","example":0},"orderFields":{"type":"array","description":"Any custom order fields attached to this invoice.","items":{"$ref":"#/components/schemas/OrderField"}},"notes":{"type":"string","description":"Notes visible to the customer at the bottom of the invoice.","example":"No vegetables please"}}},"InvoiceUpsertRequest":{"title":"InvoiceCreateRequest","type":"object","required":["currency","lineItems"],"properties":{"currency":{"type":"string","enum":["CAD","USD"],"description":"The three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code used for all monetary amounts in this invoice.\n","example":"CAD"},"lineItems":{"type":"array","description":"A list of line items to include in the invoice. Must contain at least 1 item and no more than 100.\n","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/LineItem"}},"customerId":{"type":"integer","description":"Unique customer ID to associate with this invoice.\n","example":123123,"default":0},"billingAddress":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"The billing address for this invoice.\n"},"shipping":{"allOf":[{"$ref":"#/components/schemas/Shipping"}],"description":"The shipping details for this invoice, including shipping cost, method, and destination address.\n"},"pickup":{"allOf":[{"$ref":"#/components/schemas/Pickup"}],"description":"The pickup details for this invoice. Only the pickup date is writable; the pickup name is read-only and derived from the linked customer's contact name.\n"},"tax":{"allOf":[{"$ref":"#/components/schemas/Tax"}],"description":"The invoice-level tax details.\n"},"discount":{"allOf":[{"$ref":"#/components/schemas/Discount"}],"description":"The invoice-level discount details.\n"},"type":{"type":"string","description":"The invoice type. Allowed values: ESTIMATE, QUOTE, ORDER, PURCHASE_ORDER, INVOICE, STATEMENT, REGISTRATION, CREDIT. Defaults to `INVOICE` if omitted.\n","enum":["ESTIMATE","QUOTE","ORDER","PURCHASE_ORDER","INVOICE","STATEMENT","REGISTRATION","CREDIT"],"example":"INVOICE","default":"INVOICE"},"status":{"type":"string","description":"The initial status of the invoice. Allowed values: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, IN_PROGRESS. Defaults to `DUE` if omitted.\n","enum":["CANCELLED","DUE","PAID","SHIPPED","COMPLETED","REFUNDED","IN_PROGRESS"],"example":"DUE","default":"DUE"},"convenienceFeeEnabled":{"type":"boolean","description":"Indicates whether a convenience fee is enabled for this invoice. If not provided, the system will use the merchant's global Fee Saver settings to determine this value.\n","example":true},"tipAmount":{"type":"number","format":"float","description":"Optional tip amount to include. Must be greater than zero if provided.\n","example":0.99},"invoiceNumber":{"type":"string","description":"Optional custom invoice number.  If omitted or blank, the system will generate one automatically based on the Invoice Settings.\n","example":""},"notes":{"type":"string","description":"Optional notes to display at the bottom of the invoice, visible to the customer.\n","example":"No vegetables please"}}},"Req-3":{"title":"ACH Withdraw Request Payload","type":"object","required":["bankAccountId","customerId","amount","currencyId"],"properties":{"bankAccountId":{"type":"integer","format":"int64","description":"The bank account ID to withdraw from."},"customerId":{"type":"integer","format":"int64","description":"The customer ID associated with the bank account."},"orderId":{"type":"integer","format":"int64","description":"An optional invoice ID to process the withdrawal with. If provided, the withdrawal action will perform invoice and inventory management."},"amount":{"type":"number","format":"float","description":"The amount to withdraw."},"currencyId":{"type":"integer","format":"int64","enum":[1,2],"description":"The currency of the transaction:\n  * `1` - CAD\n  * `2` - USD\n"}},"example":{"bankAccountId":1182342,"customerId":389829,"orderId":12083,"amount":79.99,"currencyId":1}},"TransactionEft":{"title":"ACH Transaction","type":"object","properties":{"id":{"type":"integer","format":"int64"},"merchantId":{"type":"integer","format":"int64"},"dateCreated":{"type":"string","format":"date-time"},"statusAuth":{"type":"integer","format":"int64"},"statusClearing":{"type":"integer","format":"int64"},"userId":{"type":"integer","format":"int64"},"batchId":{"type":"integer","format":"int64"},"bankAccountId":{"type":"integer","format":"int64"},"bankAccountL4l4":{"type":"integer","format":"int64"},"transactionType":{"type":"integer","format":"int64"},"amount":{"type":"number","format":"float"},"currency":{"type":"integer","format":"int64"},"approvalCode":{"type":"string"},"test":{"type":"integer","format":"int64"},"acquirerTransactionId":{"type":"string"},"responseMessage":{"type":"string"},"payFacTransactionId":{"type":"integer","format":"int64"},"originalTransactionId":{"type":"integer","format":"int64"},"statusBatch":{"type":"integer","format":"int64"},"dateClosed":{"type":"string","format":"date-time"}}},"Res-4":{"title":"ACH Withdraw Response Payload","type":"object","properties":{"transaction":{"$ref":"#/components/schemas/TransactionEft"}}},"Req-4":{"title":"ACH Refund Request Payload","type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"float","description":"The amount to be refunded."}},"example":{"amount":96.34}},"Res-5":{"title":"ACH Refund Response Payload","type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Successfully refunded transaction ID #1342. Refund transaction ID #1355 created."}},"Res-6":{"title":"ACH Void Response Payload","type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Successfully voided transaction ID #24732. Void transaction ID #24859 created."}},"Res-7":{"title":"ACH Cancel Response Payload","type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Successfully cancelled ACH transaction #34232."}},"AchBatch":{"title":"ACH Batch","type":"object","properties":{"batchId":{"type":"integer","format":"int64","example":861456,"description":"The id for the ACH batch."},"batchReference":{"type":"string","example":"ach-1234","description":"The reference identifier for the ACH batch."},"merchantId":{"type":"integer","format":"int64","example":8,"description":"The id of the merchant associated with this batch."},"statusBatch":{"type":"integer","format":"int64","example":1,"description":"The current state of the batch. Valid values: 1 (Open), 2 (Closed).","enum":[1,2]},"amountWithdrawals":{"type":"number","format":"float","example":120.5,"description":"The total monetary amount withdrawn."},"countWithdrawals":{"type":"number","format":"int64","example":2,"description":"The number of withdrawn transactions."},"amountDeposits":{"type":"number","format":"float","example":150,"description":"The total monetary amount deposited."},"countDeposits":{"type":"number","format":"int64","example":2,"description":"The number of deposited transactions."},"amountReversed":{"type":"number","format":"float","example":0,"description":"The total monetary amount reversed."},"countReversed":{"type":"number","format":"int64","example":0,"description":"The number of reversed transactions."},"amountRefunded":{"type":"number","format":"float","example":8.5,"description":"The total monetary amount refunded."},"countRefunded":{"type":"number","format":"int64","example":5,"description":"The number of refunded transactions."},"dateOpened":{"type":"string","example":"2026-05-06 13:01:15","description":"The timestamp indicating when the batch was opened."},"dateClosed":{"type":"string","example":"2026-05-06 13:01:15","description":"The timestamp indicating when the batch was closed."}}},"Res-8":{"title":"ACH Void Response Payload","type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Successfully settled ACH batch ID #1533."}},"CardTerminal":{"title":"Terminal","type":"object","properties":{"id":{"type":"integer","example":123,"description":"Id of the terminal."},"nickname":{"type":"string","example":"Terminal 1","description":"Nickname of terminal"},"currency":{"type":"string","example":"CAD","description":"Currency of terminal. possible values are CAD | USD"},"status":{"type":"string","example":"ACTIVE","description":"Status of Terminal. possible values are ACTIVE | INACTIVE"},"address":{"type":"object","properties":{"street1":{"type":"string","example":"Street 1"},"street2":{"type":"string","example":"Street 2"},"city":{"type":"string","example":"Calgary"},"province":{"type":"string","example":"AB","description":"Abbreviation of province"},"country":{"type":"string","example":"CAN","description":"Abbreviation of country"},"postalCode":{"type":"string","example":"H0H0H0","description":"Postal or zip code"}}}}},"Device":{"title":"Device","type":"object","properties":{"code":{"type":"string","example":"ABC1","description":"Code of the device."},"dateCreated":{"type":"string","example":"2024-02-09 14:08:08","description":"Date and time when the device was created in the format \"YYYY-MM-DD HH:MM:SS\""}}},"FailedResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of errors","items":{"type":"string","example":"An error occurred"}}}},"PaymentRequest-2":{"title":"PaymentRequest","type":"object","required":["currency","transactionAmount"],"properties":{"currency":{"type":"string","example":"CAD","description":"The currency code for the transaction amount, such as CAD or USD.\n"},"transactionAmount":{"type":"number","example":100.99,"description":"The amount to be processed, specified in the currency defined by the currency parameter.\n"},"invoiceNumber":{"type":"string","example":"INV1000","description":"An identifier for an invoice.\nIf an existing invoiceNumber is provided, Helcim will relate this transaction to that invoice.\nIf invoiceNumber provided does not exist, Helcim will create an invoice and link the provided invoiceNumber.\nIf not provided, Helcim will create an invoice.\n"},"customerCode":{"type":"string","example":"C-12345","description":"An identifier for a customer.\nIf existing customerCode is provided, Helcim will attach that customer.\nIf customerCode provided does not exist, Helcim will create a customer with the provided customerCode.\nIf not provided, Helcim will create a customer.\n"}}},"RefundRequest":{"title":"RefundRequest","type":"object","required":["transactionAmount","originalTransactionId"],"properties":{"transactionAmount":{"type":"number","example":100.99,"description":"The amount to be refunded in the currency on the original transaction.\n"},"originalTransactionId":{"type":"integer","example":1234567890,"description":"The identifier of the original transaction to refund.\nThis identifier must correspond to the transaction Id of the original transaction to be refunded.\n"}}}}}}