### Get Device Information - PHP Example

Source: https://devdocs.helcim.com/reference/getdevice

This PHP example uses cURL to fetch device information. Ensure that your API key has the required 'Read' permissions for General and Settings.

```php
<?php

$deviceCode = '{code}'; // Replace with the four-digit alphanumeric code
$apiKey = 'YOUR_API_KEY'; // Replace with your actual API key

$url = "https://api.helcim.com/v2/devices/{$deviceCode}";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Accept: application/json',
    'Authorization: Bearer ' . $apiKey
));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Device Information: ' . $response;
}

curl_close($ch);

?>
```

--------------------------------

### Get Card Batch Request (Python)

Source: https://devdocs.helcim.com/reference/getcardbatch

Example of how to make a GET request to retrieve a card batch using Python.

```Python
import http.client

conn = http.client.HTTPSConnection("api.helcim.com")

payload = ""

headers = {
  'Content-Type': "application/json",
  'Accept': "application/json"
}

conn.request("GET", "/v2/card-batches/{cardBatchId}", payload, headers)
response = conn.getresponse()
data = response.read()
print(data.decode("utf-8"))
```

--------------------------------

### Get Card Batch Request (PHP)

Source: https://devdocs.helcim.com/reference/getcardbatch

Example of how to make a GET request to retrieve a card batch using PHP.

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.helcim.com/v2/card-batches/{cardBatchId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Accept: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Get Card Batch Request (Ruby)

Source: https://devdocs.helcim.com/reference/getcardbatch

Example of how to make a GET request to retrieve a card batch using Ruby.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.helcim.com/v2/card-batches/{cardBatchId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["Accept"] = "application/json"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Get Device Information - Python Example

Source: https://devdocs.helcim.com/reference/getdevice

This Python snippet uses the 'requests' library to get device information. Make sure to replace '{code}' and 'YOUR_API_KEY' with your actual credentials.

```python
import requests

device_code = '{code}' # Replace with the four-digit alphanumeric code
api_key = 'YOUR_API_KEY' # Replace with your actual API key

url = f"https://api.helcim.com/v2/devices/{device_code}"

headers = {
    'Accept': 'application/json',
    'Authorization': f'Bearer {api_key}'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status() # Raise an exception for bad status codes
    print('Device Information:', response.json())
except requests.exceptions.RequestException as e:
    print(f'Error fetching device information: {e}')
```

--------------------------------

### Get Device Information - Node.js Example

Source: https://devdocs.helcim.com/reference/getdevice

This Node.js snippet demonstrates how to fetch device information. It uses the 'axios' library for making HTTP requests. Ensure your API key has the necessary permissions.

```javascript
const axios = require('axios');

const deviceCode = '{code}'; // Replace with the four-digit alphanumeric code
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key

axios.get(`https://api.helcim.com/v2/devices/${deviceCode}`, {
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  }
})
  .then(response => {
    console.log('Device Information:', response.data);
  })
  .catch(error => {
    console.error('Error fetching device information:', error.response ? error.response.data : error.message);
  });
```

--------------------------------

### Get Device Information - Shell Example

Source: https://devdocs.helcim.com/reference/getdevice

Use this command to retrieve device information. Replace '{code}' with the four-digit alphanumeric device code. Ensure your API key has 'Read' permissions for General and Settings.

```shell
curl -X GET \
  'https://api.helcim.com/v2/devices/{code}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Get Card Batch Request (Node.js)

Source: https://devdocs.helcim.com/reference/getcardbatch

Example of how to make a GET request to retrieve a card batch using Node.js.

```Node.js
const https = require('https');

const options = {
  hostname: 'api.helcim.com',
  port: 443,
  path: '/v2/card-batches/{cardBatchId}',
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('end', () => {
    console.log('body:', JSON.parse(data));
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();
```

--------------------------------

### Get Card Batch Request (Shell)

Source: https://devdocs.helcim.com/reference/getcardbatch

Example of how to make a GET request to retrieve a card batch using cURL.

```Shell
curl -X GET \
  "https://api.helcim.com/v2/card-batches/{cardBatchId}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
```

--------------------------------

### Get Device Information - Ruby Example

Source: https://devdocs.helcim.com/reference/getdevice

This Ruby code snippet shows how to retrieve device information using the 'httparty' gem. Remember to replace '{code}' and 'YOUR_API_KEY' with your specific values.

```ruby
require 'httparty'

device_code = '{code}' # Replace with the four-digit alphanumeric code
api_key = 'YOUR_API_KEY' # Replace with your actual API key

response = HTTParty.get("https://api.helcim.com/v2/devices/#{device_code}",
  headers: {
    'Accept' => 'application/json',
    'Authorization' => "Bearer #{api_key}"
  }
)

if response.success?
  puts "Device Information: #{response.parsed_response}"
else
  puts "Error fetching device information: #{response.code} - #{response.message}"
end
```

--------------------------------

### Get Card Batches Request (Shell)

Source: https://devdocs.helcim.com/reference/getcardbatches

Example of how to make a GET request to retrieve card batches using cURL. Ensure you have the correct base URL and any required authentication headers.

```Shell
curl -X GET \
  'https://api.helcim.com/v2/card-batches/' \
  -H 'accept: application/json'
```

--------------------------------

### Get Card Batches Request (Python)

Source: https://devdocs.helcim.com/reference/getcardbatches

Example of how to make a GET request to retrieve card batches using Python. This snippet uses the 'requests' library for making HTTP requests.

```Python
import requests

url = "https://api.helcim.com/v2/card-batches/"

headers = {
    "accept": "application/json"
}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### GET /customers/

Source: https://devdocs.helcim.com/reference/getcustomers

Retrieves a list of customers. Supports filtering and pagination.

```APIDOC
## GET /customers/

### Description
Retrieves a list of customers. Supports filtering and pagination.

### Method
GET

### Endpoint
https://api.helcim.com/v2/customers/

### Parameters
#### Query Parameters
- **search** (string) - Optional - The search term to be used for partial matching on contactName, businessName, customerCode, city, phone and email (Only use one query field per request).
- **customerCode** (string) - Optional - Existing customer code (Only use one query field per request).
- **limit** (integer) - Optional - 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.
- **page** (integer) - Optional - Specifies the page number of the results you want to retrieve.
- **includeCards** (string) - Optional - Specifies whether to return any credit cards for retrieved customers. By default no cards are returned. `yes` - return all available cards for retrieved customers.

### Response
#### Success Response (200)
- **customers** (array) - A list of customer objects.
  - **contactName** (string) - The name of the contact person.
  - **businessName** (string) - The name of the business.
  - **customerCode** (string) - The unique code for the customer.
  - **city** (string) - The city of the customer's address.
  - **phone** (string) - The customer's phone number.
  - **email** (string) - The customer's email address.
  - **cards** (array) - A list of credit card objects associated with the customer (only if includeCards=yes).

#### Response Example
```json
{
  "customers": [
    {
      "contactName": "John Doe",
      "businessName": "Doe Enterprises",
      "customerCode": "C12345",
      "city": "Anytown",
      "phone": "555-1234",
      "email": "john.doe@example.com",
      "cards": [
        {
          "type": "Visa",
          "last4": "1234"
        }
      ]
    }
  ]
}
```

#### Error Response (default)
- **message** (string) - A message describing the error.
- **code** (integer) - An error code.
```

--------------------------------

### Get Card Batches Request (Node.js)

Source: https://devdocs.helcim.com/reference/getcardbatches

Example of how to make a GET request to retrieve card batches using Node.js. This snippet uses the 'axios' library for making HTTP requests.

```Node.js
const axios = require('axios');

const options = {
  method: 'GET',
  url: 'https://api.helcim.com/v2/card-batches/',
  headers: {
    'accept': 'application/json'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
```

--------------------------------

### POST Response Sample

Source: https://devdocs.helcim.com/docs/helcimjs-transaction-responses

Example of a POST response submitted back to your website after processing a transaction.

```APIDOC
## POST Response Sample

### Description
This is an example of the POST response submitted back to your website after processing a transaction.

### Response Example
```text POST response
[response] => 1
[responseMessage] => APPROVAL
[noticeMessage] => Order Created - Customer Created
[date] => 2017-06-21
[time] => 12:23:31
[type] => purchase
[amount] => 100.00
[cardHolderName] => John Smith
[cardNumber] => 5454****5454
[cardExpiry] => 1025
[cardToken] => 5440c5e27f287875889421
[cardType] => MasterCard
[transactionId] => 112415310
[avsResponse] => X
[cvvResponse] => M
[approvalCode] => 102542
[orderNumber] => INV10010
[customerCode] => CST2000
[currency] => CAD
[xml] => XML-DOCUMENT-SEE-BELOW
```
```

--------------------------------

### XML Response Sample

Source: https://devdocs.helcim.com/docs/helcimjs-transaction-responses

Example of an XML response containing transaction information, provided when 'Include XML in Response' is enabled.

```APIDOC
## XML Response Sample

### Description
When 'Include XML in Response' is toggled on for your Helcim.js configuration, the response contains an XML document with relevant transaction information.

### Response Example
```xml XML response
<?xml version="1.0"?>
<message>
  <response>1</response>
  <responseMessage>APPROVAL</responseMessage>
  <noticeMessage>New Card Stored - New Customer Created - New Order Created - Order Marked as Paid</noticeMessage>
  <date>2024-04-24</date>
  <time>16:14:42</time>
  <type>purchase</type>
  <amount>456.00</amount>
  <currency>CAD</currency>
  <cardHolderName>Jessica Smith</cardHolderName>
  <cardNumber>5454 **** **** 5454</cardNumber>
  <cardExpiry>0138</cardExpiry>
  <cardToken>5c92996b7d573c1b15fc6e</cardToken>
  <cardType>Mastercard</cardType>
  <transactionId>42688929</transactionId>
  <avsResponse>X</avsResponse>
  <cvvResponse></cvvResponse>
  <approvalCode>T3E3ST</approvalCode>
  <orderNumber>INV8792466</orderNumber>
  <customerCode>CST123457143</customerCode>
  <includeXML>1</includeXML>
</message>
```
```

--------------------------------

### Example Add-on Object Structure

Source: https://devdocs.helcim.com/docs/recurring-add-ons

This JSON object represents a typical add-on configuration. It includes basic information, pricing, and quantity settings.

```json
{
  "id": 181,
  "dateCreated": "2024-06-05 14:59:30",
  "dateUpdated": "2024-06-05 15:22:06",
  "name": "Example Addon",
  "description": "Test",
  "amount": 10,
  "frequency": "recurring",
  "isQuantityEditable": true
 }
```

--------------------------------

### Example Payment Plan Object Structure

Source: https://devdocs.helcim.com/docs/recurring-payment-plans

This JSON object represents a typical payment plan configuration. It includes details like name, description, currency, recurring amount, billing period, and tax information.

```json
{
  "id": 6395,
  "dateCreated": "2024-10-04 09:19:16",
  "dateUpdated": "2024-10-04 15:31:13",
  "userId": 4279294,
  "name": "Test Payment Plan",
  "businessEmail": "",
  "businessName": "",
  "description": "Description of Payment Plan",
  "type": "subscription",
  "status": "active",
  "currency": "CAD",
  "cardTerminalId": 54181,
  "setupAmount": 0,
  "recurringAmount": 75,
  "billingPeriod": "daily",
  "billingPeriodIncrements": 1,
  "dateBilling": "Sign-up",
  "termType": "forever",
  "freeTrialPeriod": 0,
  "taxType": "customer",
  "termLength": 1,
  "paymentMethod": "card",
  "defaultPaymentLinkId": 0,
  "addOnIds": [
    429,
    430,
    431,
    432
  ]
}
```

--------------------------------

### Get Card Batches Request (PHP)

Source: https://devdocs.helcim.com/reference/getcardbatches

Example of how to make a GET request to retrieve card batches using PHP. This snippet uses cURL to send the HTTP request.

```PHP
<?php

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, 'https://api.helcim.com/v2/card-batches/');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('accept: application/json'));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error # " . $err;
} else {
  echo $response;
}
?>
```

--------------------------------

### Example Subscription Object

Source: https://devdocs.helcim.com/docs/recurring-subscriptions

This JSON object represents a single subscription. It includes details like customer code, billing dates, and amounts.

```json
{
  "id": 19849,
  "dateCreated": "2024-10-04 09:28:19",
  "dateUpdated": "0000-00-00 00:00:00",
  "dateActivated": "2024-10-04",
  "dateBilling": "2025-03-06",
  "status": "active",
  "paymentPlanId": 6395,
  "customerCode": "CST1044",
  "timesBilled": 118,
  "setupAmount": 0,
  "recurringAmount": 75,
  "freeTrialPeriod": 0,
  "hasFailedPayments": "true",
  "isProrated": "no",
  "addOnsIds": [
    741,
    742
  ]
}
```

--------------------------------

### Get Card Batches Request (Ruby)

Source: https://devdocs.helcim.com/reference/getcardbatches

Example of how to make a GET request to retrieve card batches using Ruby. This snippet uses the 'httparty' gem for making HTTP requests.

```Ruby
require 'httparty'

response = HTTParty.get('https://api.helcim.com/v2/card-batches/',
  headers: { 'accept' => 'application/json' })

puts response.body
```

--------------------------------

### POST /v2/add-ons

Source: https://devdocs.helcim.com/reference/add-on-create

Create one or more add-ons to link to payment plans and subscriptions.

```APIDOC
## POST /v2/add-ons

### Description
Create one or more add-ons to link to payment plans and subscriptions.

### Method
POST

### Endpoint
https://api.helcim.com/v2/add-ons

### Headers
- **api-token** (string) - required - Your API access token for authentication and access to the Helcim API

### Request Body
- **addOns** (array of objects) - required - Information required to create one or more add-ons.
  - **ADD** (object) - required - Represents a single add-on.

### Request Example
```json
{
  "addOns": [
    {
      "name": "Example Add-on",
      "price": "10.00",
      "type": "service"
    }
  ]
}
```

### Response
#### Success Response (201)
Successful add-on creation. The response body contains the data representation of all newly created add-ons.
- **id** (string) - The unique identifier for the created add-on.
- **name** (string) - The name of the add-on.
- **price** (string) - The price of the add-on.
- **type** (string) - The type of the add-on.

#### Response Example
```json
{
  "addOns": [
    {
      "id": "addon_12345",
      "name": "Example Add-on",
      "price": "10.00",
      "type": "service"
    }
  ]
}
```

#### Error Responses
- **400**: You are initiating a request with invalid parameter and/or body values.
- **401**: You are not authorized to access this resource. Please ensure that you are authenticated, and that you are using the `api-token` header.
- **403**: You do not have permission to access this resource. Please ensure you are both authenticated and that you have the required roles/permissions active.
- **500**: Helcim internal server error encountered.
```

--------------------------------

### Example Subscription with Payment Sub-object

Source: https://devdocs.helcim.com/docs/recurring-subscriptions

This JSON object shows a subscription that includes its associated payment sub-objects. The payment sub-object provides the status and details of a specific payment.

```json
{
  "id": 19849,
  "dateCreated": "2024-10-04 09:28:19",
  "dateUpdated": "0000-00-00 00:00:00",
  "dateActivated": "2024-10-04",
  "dateBilling": "2025-03-06",
  "status": "active",
  "paymentPlanId": 6395,
  "customerCode": "CST1044",
  "timesBilled": 118,
  "setupAmount": 0,
  "recurringAmount": 75,
  "freeTrialPeriod": 0,
  "hasFailedPayments": "true",
  "isProrated": "no",
  "payments": [
    {
      "id": 89338,
      "setupAmount": 0,
      "recurringAmount": 75,
      "addOnAmount": 0,
      "amount": 75,
      "taxAmount": 3.75,
      "status": "approved",
      "dateDue": "2024-10-04 00:00:00",
      "dateProcessed": "2024-10-04 09:28:20",
      "paymentNumber": 1,
      "numberOfRetries": 0
    }
  ]
}
```

--------------------------------

### POST /customers/

Source: https://devdocs.helcim.com/reference/createcustomer

Creates a new customer in the Helcim system. You can provide a customer code or have one automatically generated. Either a contact name or a business name must be provided.

```APIDOC
## POST /customers/

### Description
Creates a new customer.

### Method
POST

### Endpoint
https://api.helcim.com/v2/customers/

### Parameters
#### Request Body
- **customerCode** (string) - Optional - The unique customer code. If blank, it will be automatically generated.
- **contactName** (string) - Optional - The primary contact name (full name) of the customer.
- **businessName** (string) - Optional - The business name of the customer. There must be either a contact name or business name present.
- **cellPhone** (string) - Optional - The cell phone number of the customer.
- **billingAddress** (object) - Optional - Address object.
- **shippingAddress** (object) - Optional - Address object.

### Response
#### Success Response (200)
- **message** (string) - Description of the success message.

#### Response Example
```json
{
  "message": "Customer created successfully."
}
```
```

--------------------------------

### POST Response Sample

Source: https://devdocs.helcim.com/docs/helcimjs-transaction-responses

This is an example of the POST response submitted back to your website's server after processing a transaction. It contains key-value pairs of transaction details.

```text
[response] => 1
[responseMessage] => APPROVAL
[noticeMessage] => Order Created - Customer Created
[date] => 2017-06-21
[time] => 12:23:31
[type] => purchase
[amount] => 100.00
[cardHolderName] => John Smith
[cardNumber] => 5454****5454
[cardExpiry] => 1025
[cardToken] => 5440c5e27f287875889421
[cardType] => MasterCard
[transactionId] => 112415310
[avsResponse] => X
[cvvResponse] => M
[approvalCode] => 102542
[orderNumber] => INV10010
[customerCode] => CST2000
[currency] => CAD
[xml] => XML-DOCUMENT-SEE-BELOW
```

--------------------------------

### GET /v2/ach/batches

Source: https://devdocs.helcim.com/reference/getmanyachbatches

Collects all ACH batches.

```APIDOC
## GET /v2/ach/batches

### Description
Collects all ACH batches.

### Method
GET

### Endpoint
https://api.helcim.com/v2/ach/batches

### Responses
#### Success Response (200)
All ACH Batches.

#### Error Responses
- **400**: Invalid request.
- **403**: User does not have valid permissions.
- **500**: Unexpected internal error.
```

--------------------------------

### Partner Registration URL Format

Source: https://devdocs.helcim.com/docs/connected-account-registrations

This is the example format for the partner registration URL, including the partner token and connected account identifier parameters.

```plaintext
'https://hub.helcim.com/signup/register?pt="partner_token"&cid="connected_account_identifier"'
```

--------------------------------

### GET /v2/ach/transactions

Source: https://devdocs.helcim.com/reference/getmanyachtransactions

Retrieves all ACH transactions.

```APIDOC
## GET /v2/ach/transactions

### Description
Collects all ACH transactions.

### Method
GET

### Endpoint
https://api.helcim.com/v2/ach/transactions

### Responses
#### Success Response (200)
All ACH transactions.

#### Error Responses
- **400**: Invalid request.
- **403**: User does not have valid permissions.
- **500**: Unexpected internal error.
```

--------------------------------

### Get transactions

Source: https://devdocs.helcim.com/docs/payments

Retrieve a list of existing transaction objects.

```APIDOC
## GET /getcardtransactions

### Description
Retrieves a list of existing transaction objects.

### Method
GET

### Endpoint
/getcardtransactions

### Parameters
#### Path Parameters
None

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of transactions to return.
- **offset** (integer) - Optional - The number of transactions to skip before returning results.
- **customer_id** (string) - Optional - Filter transactions by customer ID.
- **start_date** (string) - Optional - Filter transactions starting from this date (YYYY-MM-DD).
- **end_date** (string) - Optional - Filter transactions up to this date (YYYY-MM-DD).

### Request Example
GET /getcardtransactions?limit=10&offset=0&customer_id=cust_123

### Response
#### Success Response (200)
- **transactions** (array) - An array of transaction objects.
  - **transaction_id** (string) - The unique identifier for the transaction.
  - **amount** (string) - The transaction amount.
  - **currency** (string) - The currency code.
  - **status** (string) - The status of the transaction.
  - **transaction_date** (string) - The date and time of the transaction.

#### Response Example
{
  "transactions": [
    {
      "transaction_id": "txn_12345abcde",
      "amount": "10.00",
      "currency": "CAD",
      "status": "approved",
      "transaction_date": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Get Add-on API

Source: https://devdocs.helcim.com/docs/recurring-add-ons

Retrieve a single add-on by its `id`.

```APIDOC
## GET /v2.2/add-ons/{id}

### Description
Retrieve a single add-on by its `id`.

### Method
GET

### Endpoint
/v2.2/add-ons/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the add-on to retrieve.

### Response
#### Success Response (200)
- **add_on** (object) - The retrieved add-on object.
  - **id** (string) - The ID of the add-on.
  - **name** (string) - The name of the add-on.
  - **price** (string) - The price of the add-on.

#### Response Example
{
  "add_on": {
    "id": "addon_123",
    "name": "Example Add-on",
    "price": "10.00"
  }
}
```

--------------------------------

### POST /subscriptions

Source: https://devdocs.helcim.com/reference/subscription-create

Create one or more subscriptions to your payment plans. This endpoint allows for the creation of subscriptions, handling associated add-ons, and processing initial payments.

```APIDOC
## POST /subscriptions

### Description
Create one or more subscriptions to your payment plans. This endpoint allows for the creation of subscriptions, handling associated add-ons, and processing initial payments. The response includes details of newly created subscriptions, the first payment status, and applied active add-ons.

### Method
POST

### Endpoint
https://api.helcim.com/v2/subscriptions

### Parameters
#### Header Parameters
- **api-token** (string) - Required - Your API access token for authentication and access to the Helcim API.
- **idempotency-key** (string) - Required - A unique 25 character alphanumeric key to ensure the request is idempotent. Requests containing keys used in previously successful requests will be rejected.

### Request Body
- **subscriptionCreationReq** (object) - Required - Information required to create one or more subscriptions. Refer to the components section for schema details.

### Request Example
```json
{
  "example": "subscriptionCreationReq schema details would be here"
}
```

### Response
#### Success Response (201)
- **subscriptionCreationRes** (object) - Successful subscription creation. The response body contains the data representation of all newly created subscriptions, the first payment, and applied active add-ons. If any created subscriptions were immediately billed the returned payment will indicate whether the billing was approved or declined. Only active add-ons will be present in the response, one time add-ons that were immediately billed will not be present.

#### Error Responses
- **400** - Bad Request: You are initiating a request with invalid parameter and/or body values.
- **401** - Unauthorized: You are not authorized to access this resource. Please ensure that you are authenticated, and that you are using the `api-token` header.
- **403** - Forbidden: You do not have permission to access this resource. Please ensure you are both authenticated and that you have the required roles/permissions active.
- **500** - Internal Server Error: Helcim internal server error encountered.

#### Response Example
```json
{
  "example": "subscriptionCreationRes schema details would be here"
}
```
```

--------------------------------

### Get transaction

Source: https://devdocs.helcim.com/docs/payments

Retrieve a specific existing transaction object by its ID.

```APIDOC
## GET /getcardtransaction

### Description
Retrieves a specific existing transaction object by its ID.

### Method
GET

### Endpoint
/getcardtransaction

### Parameters
#### Path Parameters
None

#### Query Parameters
- **transaction_id** (string) - Required - The unique identifier for the transaction.

### Request Example
GET /getcardtransaction?transaction_id=txn_12345abcde

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the transaction.
- **amount** (string) - The transaction amount.
- **currency** (string) - The currency code.
- **status** (string) - The status of the transaction.
- **transaction_date** (string) - The date and time of the transaction.
- **customer_id** (string) - The ID of the customer associated with the transaction.
- **order_id** (string) - The order ID associated with the transaction.

#### Response Example
{
  "transaction_id": "txn_12345abcde",
  "amount": "10.00",
  "currency": "CAD",
  "status": "approved",
  "transaction_date": "2023-10-27T10:00:00Z",
  "customer_id": "cust_123",
  "order_id": "order_xyz"
}
```

--------------------------------

### HelcimPay.js Initialization with Confirmation Screen Option

Source: https://devdocs.helcim.com/docs/customizing-your-helcimpayjs-modal

Use the `confirmationScreen` parameter during HelcimPay.js initialization to choose between the new confirmation screen (true) or the legacy toast message (false or omitted).

```javascript
HelcimPay.init({
  "merchantId": "YOUR_MERCHANT_ID",
  "//": "Set confirmationScreen to true to use the new confirmation screen style.",
  "confirmationScreen": true
});
```

--------------------------------

### Get Invoice

Source: https://devdocs.helcim.com/reference/getinvoice

Retrieves the details of a specific invoice using its unique ID.

```APIDOC
## GET /v2/invoices/{invoiceId}

### Description
Retrieves the details of a specific invoice using its unique ID.

### Method
GET

### Endpoint
https://api.helcim.com/v2/invoices/{invoiceId}

### Parameters
#### Path Parameters
- **invoiceId** (string) - Required - The unique ID of the invoice to retrieve.

### Response
#### Success Response (200)
- **invoice** (object) - Details of the retrieved invoice.

#### Response Example
{
  "invoice": {
    "id": "inv_12345",
    "amount": "100.00",
    "currency": "USD",
    "status": "paid",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```

--------------------------------

### Get Customer

Source: https://devdocs.helcim.com/reference/getcustomer

Retrieves the details of a specific customer using their unique ID.

```APIDOC
## GET /customers/{customerId}

### Description
Retrieves the details of a specific customer.

### Method
GET

### Endpoint
https://api.helcim.com/v2/customers/{customerId}

### Parameters
#### Path Parameters
- **customerId** (integer) - Required - The Id of the customer

### Response
#### Success Response (200)
- **customer details** (object) - Contains the customer's information.

#### Response Example
{
  "example": "{\"id\": \"123\", \"name\": \"John Doe\", \"email\": \"john.doe@example.com\"}"
}
```

--------------------------------

### GET /v2/payment-plans

Source: https://devdocs.helcim.com/reference/payment-plan-collection

Retrieves a collection of payment plans, with options to filter and sort the results.

```APIDOC
## GET /v2/payment-plans

### Description
Query all payment plans filtered by the provided parameters.

### Method
GET

### Endpoint
https://api.helcim.com/v2/payment-plans

### Query Parameters
- **id** (integer) - Optional - The payment plan id.
- **name** (string) - Optional - Given payment plan name. Only exact matches are currently supported.
- **type** (string) - Optional - The payment plan billing type: `subscription` or `cycle`.
- **status** (string) - Optional - The payment plan activity status: `active` or `inactive`.
- **currency** (string) - Optional - The currency subscriptions to the payment plan are billed with. Allowed values: `CAD`, `USD`.
- **setupAmount** (float) - Optional - The monetary amount charged at time of sign-up for subscriptions to the payment plan.
- **recurringAmount** (float) - Optional - The recurring monetary amount charged for subscriptions to the payment plan.
- **billingPeriod** (string) - Optional - The cycle at which subscriptions to the payment plan are billed. Allowed values: `daily`, `weekly`, `monthly`, `yearly`.
- **billingPeriodIncrements** (integer) - Optional - The frequency to which subscriptions for the payment plan are processed based on billing period.
- **dateBilling** (string) - Optional - The date subscriptions to the payment plan are billed. Requires specific formatting depending on the plan's billing cycle.
- **termType** (string) - Optional - Identifies whether subscriptions to the plan expire after a set number of billings. Allowed values: `forever`, `expires`.
- **freeTrialPeriod** (integer) - Optional - Free trial length (in days) for subscriptions to the payment plan.
- **taxType** (string) - Optional - The tax rate applied to subscriptions to the payment plan. Allowed values: `no_tax`, `customer`, `merchant`.
- **taxCalculation** (string) - Optional - The specific country and province/state tax(es) applied to the tax rate calculation. Allowed values: `country_only`, `country_province`, `province_only`.
- **paymentMethod** (string) - Optional - The allowed payment methods subscriptions to this plan can utilize. Allowed values: `card`, `bank`, `card_bank`.
- **addOnId** (integer) - Optional - Add-on linked to the payment plan.
- **sortBy** (string) - Optional - Sorting preference of returned resources. Format: `PARAMETER.ORDER` (e.g., `id.asc`). Allowed order values: `asc`, `desc`.
- **limit** (integer) - Optional - The maximum number of resources to return (max 100).
- **offset** (integer) - Optional - Offset for pagination.

### Response
#### Success Response (200)
- **id** (integer) - Description
- **name** (string) - Description
- **type** (string) - Description
- **status** (string) - Description
- **currency** (string) - Description
- **setupAmount** (float) - Description
- **recurringAmount** (float) - Description
- **billingPeriod** (string) - Description
- **billingPeriodIncrements** (integer) - Description
- **dateBilling** (string) - Description
- **termType** (string) - Description
- **freeTrialPeriod** (integer) - Description
- **taxType** (string) - Description
- **taxCalculation** (string) - Description
- **paymentMethod** (string) - Description
- **addOnId** (integer) - Description

#### Response Example
{
  "example": "[Response body example]"
}
```

--------------------------------

### Complete Helcim.js HTML Form Example

Source: https://devdocs.helcim.com/docs/html-form-structure

This HTML form demonstrates the integration of Helcim.js, including the script inclusion and a full set of optional input fields for processing transactions. Remember to replace the placeholder token with your actual Helcim.js Configuration token.

```html
<!--SCRIPT-->
// Included in the head element of your website
<script type="text/javascript" src="https://secure.myhelcim.com/js/version2.js"></script>

<!--FORM-->
// Included in the body element of your website
<form name="helcimForm" id="helcimForm" action="your-checkout-page.php" method="POST">

	<!--RESULTS-->
	<div id="helcimResults"></div>

	<!--SETTINGS-->
	<input type="hidden" id="token" value="58ae1d44d7ac6959332969">
	<input type="hidden" id="language" value="en">

	<!--CARD-INFORMATION-->
	Card Token: <input type="text" id="cardToken" value="1"><br/>
	Credit Card Number: <input type="text" id="cardNumber" value=""><br/>
	Expiry Month: <input type="text" id="cardExpiryMonth" value="">
 	Expiry Year: <input type="text" id="cardExpiryYear" value=""><br/>
	CVV: <input type="text" id="cardCVV" value=""><br/>

	<!--AVS-INFORMATION-->
	Card Holder Name: <input type="text" id="cardHolderName" value=""><br/>
	Card Holder Address: <input type="text" id="cardHolderAddress" value=""><br/>
	Card Holder Postal Code: <input type="text" id="cardHolderPostalCode" value=""><br/>

	<!--OPTIONAL-AMOUNT-->
	Amount: <input type="text" id="amount" value="100.00"><br/>
	<input type="hidden" id="amountShipping" value="2.00">
	<input type="hidden" id="amountTax" value="3.00">

	<!--OPTIONAL-BILLING-ADDRESS-->
	Billing - Contact Name: <input type="text" id="billing_contactName" value=""><br/>
	Billing - Business Name: <input type="text" id="billing_businessName" value=""><br/>
	Billing - Address Street 1: <input type="text" id="billing_street1" value=""><br/>
	Billing - Address Street 2: <input type="text" id="billing_street2" value=""><br/>
	Billing - City: <input type="text" id="billing_city" value=""><br/>
	Billing - Province: <input type="text" id="billing_province" value=""><br/>
	Billing - Postal Code: <input type="text" id="billing_postalCode" value=""><br/>
	Billing - Country: <input type="text" id="billing_country" value=""><br/>
	Billing - Phone Number: <input type="text" id="billing_phone" value=""><br/>
	Billing - Email Address: <input type="text" id="billing_email" value=""><br/>
	Billing - Fax: <input type="text" id="billing_fax" value=""><br/>

	<!--OPTIONAL-SHIPPING-ADDRESS-->
	Shipping - Contact Name: <input type="text" id="shipping_contactName" value=""><br/>
	Shipping - Business Name: <input type="text" id="shipping_businessName" value=""><br/>
	Shipping - Address Street 1: <input type="text" id="shipping_street1" value=""><br/>
	Shipping - Address Street 2: <input type="text" id="shipping_street2" value=""><br/>
	Shipping - City: <input type="text" id="shipping_city" value=""><br/>
	Shipping - Province: <input type="text" id="shipping_province" value=""><br/>
	Shipping - Postal Code: <input type="text" id="shipping_postalCode" value=""><br/>
	Shipping - Country: <input type="text" id="shipping_country" value=""><br/>
	Shipping - Phone Number: <input type="text" id="shipping_phone" value=""><br/>
	Shipping - Email Address: <input type="text" id="shipping_email" value=""><br/>
	Shipping - Fax: <input type="text" id="shipping_fax" value=""><br/>

	<!--OPTIONAL-ORDER-->
	Order Number: <input type="text" id="orderNumber" value="4"><br/>

	<!--OPTIONAL-CUSTOMER-->
	Customer Code: <input type="text" id="customerCode" value="3"><br/>

	<!--OPTIONAL-COMMENTS-->
	Comments: <input type="text" id="comments" value=""><br/>

	<!--OPTIONAL-ITEM-->
	ITEM 1 - SKU: <input type="text" id="itemSKU1" value="SKU100"><br/>
	ITEM 1 - Description: <input type="text" id="itemDescription1" value="Item 1 Description"><br/>
	ITEM 1 - Serial Number: <input type="text" id="itemSerialNumber1" value="SN10100100101"><br/>
	ITEM 1 - Quantity: <input type="text" id="itemQuantity1" value="2"><br/>
	ITEM 1 - Price: <input type="text" id="itemPrice1" value="10.00"><br/>
	ITEM 1 - Total: <input type="text" id="itemTotal1" value="20.00"><br/>

	ITEM 2 - SKU: <input type="text" id="itemSKU2" value="SKU200"><br/>
	ITEM 2 - Description: <input type="text" id="itemDescription2" value="Item 2 Description"><br/>
	ITEM 2 - Serial Number: <input type="text" id="itemSerialNumber2" value="SN20200200202"><br/>
	ITEM 2 - Quantity: <input type="text" id="itemQuantity2" value="2"><br/>
	ITEM 2 - Price: <input type="text" id="itemPrice2" value="15.00"><br/>
	ITEM 2 - Total: <input type="text" id="itemTotal2" value="30.00"><br/>

	<!--BUTTON-->
	<input type="button" id="buttonProcess" value="Process" onclick="javascript:helcimProcess();">

</form>
```

--------------------------------

### Get Subscription by ID

Source: https://devdocs.helcim.com/docs/recurring-subscriptions

Retrieves a specific subscription and its payment sub-objects using the subscription ID.

```APIDOC
## GET /subscriptions/{id}

### Description
Retrieves a single subscription by its ID, including its associated payment sub-objects. This is useful for inspecting the status and details of individual subscription payments.

### Method
GET

### Endpoint
/subscriptions/{id}

### Path Parameters
- **id** (integer) - Required - The unique identifier of the subscription.

### Response
#### Success Response (200)
- **id** (integer) - The subscription ID.
- **payments** (array) - An array of payment sub-objects associated with the subscription.
  - **id** (integer) - The payment ID.
  - **status** (string) - The status of the payment (e.g., "approved").
  - **amount** (float) - The payment amount.
  - **taxAmount** (float) - The tax amount for the payment.
  - **dateDue** (string) - The due date of the payment.
  - **dateProcessed** (string) - The date the payment was processed.

### Response Example
```json
{
  "id": 19849,
  "dateCreated": "2024-10-04 09:28:19",
  "dateUpdated": "0000-00-00 00:00:00",
  "dateActivated": "2024-10-04",
  "dateBilling": "2025-03-06",
  "status": "active",
  "paymentPlanId": 6395,
  "customerCode": "CST1044",
  "timesBilled": 118,
  "setupAmount": 0,
  "recurringAmount": 75,
  "freeTrialPeriod": 0,
  "hasFailedPayments": "true",
  "isProrated": "no",
  "payments": [
    {
      "id": 89338,
      "setupAmount": 0,
      "recurringAmount": 75,
      "addOnAmount": 0,
      "amount": 75,
      "taxAmount": 3.75,
      "status": "approved",
      "dateDue": "2024-10-04 00:00:00",
      "dateProcessed": "2024-10-04 09:28:20",
      "paymentNumber": 1,
      "numberOfRetries": 0
    }
  ]
}
```
```