Helcim Card Terminal & Device API

{"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

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/helcim/refs/heads/main/openapi/helcim-api.json