### Setup Protect.js with Authorization Token

Source: https://api.sandbox.paytrace.com/v3/redoc

Initialize Protect.js by providing your client key for authorization. This setup returns an instance object used for processing and tokenizing payment fields.

```javascript
<script>
// Minimal Protect.js setup call
PTPayment.setup({
  authorization: { clientKey: <clientKey> }
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});
</script>
```

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

### Dynamic Styling Examples for PTPayment

Source: https://api.sandbox.paytrace.com/v3/redoc

Demonstrates how to use PTPayment methods for dynamic styling of payment fields. Implement these within a .then method after a promise resolves. Includes examples for getControl, theme, and style.

```javascript
//PTPayment.getControl examples
PTPayment.getControl("securityCode").label.text("CSC");
PTPayment.getControl("creditCard").label.text("CC");
PTPayment.getControl("expiration").label.text("Exp Date");

//PTPayment.theme examples
PTPayment.theme('horizontal');
PTPayment.theme('above the line');
PTPayment.theme('below the line');
PTPayment.theme('label-none');
PTPayment.theme('label-extended-top');

//PTPayment.style examples
PTPayment.style({'cc': {'border_style': 'dashed'}});
PTPayment.style({'code': {'label_color': 'red'}});
PTPayment.style({'exp': {'type': 'textbox'}});
```

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

### Get Client Credentials Token

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This example shows how to obtain an access token using the client_credentials grant type. Replace 'YourApiUsername' and 'YourApiPassword' with your actual PayTrace API credentials.

```APIDOC
## Get Client Credentials or Refresh Token

For grant_type=client_credentials the client_id should be your PayTrace API username, while the client_id is your PayTrace API password.

Example of the initial client_credentials request:
```
curl 'https://api.paytrace.com/v3/token' -XPOST \
  -H'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=client_credentials' \
  --data-raw 'client_id=YourApiUsername' \
  --data-raw 'client_secret=YourApiPassword'
```
```

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

### Get Checkout Design Request Example

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Example of how to construct a GET request to retrieve a specific checkout design. The `design_id` is a path parameter. The `X-Integrator-Id` and `X-Permalinks` headers are optional but can be useful for correlation and immutable IDs.

```http
GET /v3/checkout/design/{design_id}
Host: api.sandbox.paytrace.com
Authorization: Bearer <token>
X-Integrator-Id: <your_integrator_id>
X-Permalinks: true
```

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

### Permalinks Header Example

Source: https://api.sandbox.paytrace.com/v3/redoc

This example demonstrates how to use the X-Permalinks header to retrieve immutable UUIDs for customer records. It shows the difference in API calls with and without the header, and how to use UUIDs for lookups.

```http
GET :url/customer/87654321
Authorization: Bearer <token>
X-Permalinks: true
```

```http
GET :url/customer/50f55406-83e5-4032-a743-c3051a933e2d
Authorization: Bearer <token>
X-Permalinks: true
```

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

### Token Response Sample

Source: https://api.sandbox.paytrace.com/v3/redoc

Example of a successful response when requesting an access token.

```json
{
  "access_token": "4656d6f6132333:4656d6f6132333:2b607b9a44720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214",
  "refresh_token": "4656d6f6132333:4656d6f6132333:2b607b9a44720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_expires_in": 3600,
  "username": "test_user"
}
```

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

### Get Token API Request Sample

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This is a sample request body for the 'Get Token' endpoint. It requires a clientKey.

```json
{
  "clientKey": "string"
}
```

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

### Successful Response for Get Checkout Setting

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Sample JSON response for a successful retrieval of checkout settings.

```json
{
  "silent_post": "https://example.com/payment-response",
  "terms_conditions_link": "http://example.com/terms-redirect-link",
  "payment_approved_link": "http://example.com/payment-approved-link",
  "payment_declined_link": "http://example.com/payment-declined-link",
  "return_method": "HYPERLINK",
  "email_required": true,
  "billing_address_required": true,
  "csc_required": true,
  "merchant_id": 12345,
  "user": "nick",
  "invoice_expiration_days": 14,
  "id": 246810
}
```

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

### Setup Protect.js Payment Form

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Initializes Protect.js with a client key for setting up the payment form. Use the returned instance object to process and tokenize sensitive data.

```javascript
<script>
// Minimal Protect.js setup call
PTPayment.setup({ 
  authorization: { clientKey: <clientKey> } 
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});
</script>

```

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

### Get Refresh Token

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This example demonstrates how to obtain a new access token using a refresh token. This is useful for maintaining authenticated sessions without re-entering credentials.

```APIDOC
Example of the refresh_token request:
```
curl 'https://api.paytrace.com/v3/token?grant_type=refresh_token' \
  '&refresh_token=<value of your refresh token>' \
  -XPOST
```
```

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

### Example Customer Record Fetch with X-Permalinks

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Demonstrates fetching a customer record using a UUID when the X-Permalinks header is enabled. This ensures immutable record retrieval.

```http
GET :url/customer/50f55406-83e5-4032-a743-c3051a933e2d
Authorization: Bearer <token>
X-Permalinks: true
```

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

### Request Payload Example

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This is an example of a JSON payload for a transaction request. Ensure all required fields are populated correctly.

```json
{
  "invoice_id": "9ecaffcf-48b4-480a-91b4-a0c4d8786806",
  "is_invoice_pay": false,
  "silent_post": "https://example.com/payment-response",
  "amount": 80.55,
  "billing_address": {
    "street": "1 Main St.",
    "street2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "country": "US",
    "postal_code": "85284",
    "county": "Oakland"
  },
  "billing_name": "Steve Smith",
  "csc": "htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY             u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3             jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb             oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr            9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
  "billing_email": "email@domain.com",
  "billing_phone": "string",
  "customer_reference_id": "PO123456",
  "description": "business services",
  "force_partial_auth_capability": true,
  "invoice_number": "17",
  "merchant_id": 246810,
  "custom_dba": "Doing Business As Test Company",
  "return_clr": false,
  "customer_id": 0,
  "shipping_address": {
    "street": "1 Main St.",
    "street2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "country": "US",
    "postal_code": "85284",
    "county": "Oakland"
  },
  "shipping_name": "Steve Smith",
  "tax_amount": "2.16",
  "discretionary_data": [
    {
      "disc_id": 0,
      "value": "string"
    }
  ],
  "surcharge_info": { }
}
```

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

### Fetch Customer Record with X-Permalinks

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Examples demonstrate how to fetch a customer record using either the customer ID or the customer UUID, with and without the X-Permalinks header.

```http
GET :url/customer/87654321
Authorization: Bearer <token>
```

```http
GET :url/customer/50f55406-83e5-4032-a743-c3051a933e2d
Authorization: Bearer <token>
X-Permalinks: true
```

```http
GET :url/customer/87654321
Authorization: Bearer <token>
X-Permalinks: true
```

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

### Configure Static Styling and Authorization

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This snippet demonstrates how to configure static styling options for input and label elements, along with setting up authorization using a client key. Use this when initializing the PayTrace instance to customize the appearance and enable authentication.

```javascript
{
    'input_border_width':'2px',
    'input_font':'arial, cursive, fantasy',
    'input_font_weight':'400',
    'input_margin':'5px 0px 5px 0px',
    'input_padding':'0px 5px 0px 5px',
    'label_color':'#5D99CA',
    'label_size':'16px',
    'label_width':'150px',
    'label_font':'arial, fantasy, serif',
    'label_font_weight':'normal',
    'label_margin':'5px 0px 0px 0px',
    'label_padding':'2px 5px 2px 5px',
    'label_border_style':'dashed',
    'label_border_color':'#EF9F6D',
    'label_border_radius':'0px',
    'label_border_width':'2px',
    'background_color':'white',
    'height':'25px',
    'width':'85px',
    'padding_bottom':'2px',
    'type':'dropdown'
   },
   'body': {
    'background_color':'white'
   }
  },
 authorization:
  {
   'clientKey': clientKey
  }
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});
```

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

### JSON Request Payload Example

Source: https://api.sandbox.paytrace.com/v3/redoc

This is an example of a JSON payload for a transaction request. Ensure all required fields are populated correctly.

```json
{
  "amount": 80.55,
  "billing_address": {
    "street": "1 Main St.",
    "street2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "country": "US",
    "postal_code": "85284",
    "county": "Oakland"
  },
  "billing_name": "Steve Smith",
  "csc": "htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY             u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3             jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb             oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr            9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
  "billing_email": "email@domain.com",
  "billing_phone": "string",
  "customer_reference_id": "PO123456",
  "description": "business services",
  "force_partial_auth_capability": true,
  "invoice_number": "17",
  "merchant_id": 246810,
  "custom_dba": "Doing Business As Test Company",
  "return_clr": false,
  "swipe": "If this is a Magensa Reader encrypted: <br>             %B403000007. 004896^YOU/A GIFT FOR           ^3001000000000000000000000000000?;             4030000070004896=30010000000000000000?|0600|02A2B0CF2BE290CDF59DF1AE911E58170FE96              B48D3743EF96B55FC679DD331880471F54BCD34DB2A5C5773C5EC4DA60D4B26A2712658159F4FAEA26E7             FCAE7588E5AFE905A5E33039D3FC76C2EA15FF1|1E2ED1FBAD9FCE68031F5BCC3A3F380F1B13B234A28791             93B2DE4D75477C33036F25602B33373B26||61403000|67CF6FD161D11FC8E86DFA58E107F08C43D43593478             4A58078C01D62CD55EDF3DEC4BEB8F8036B1C7E3D449EE12A3B5551603809F0BCA03B|B03F953080911AA|F7914             A6718FB78CF|9011880B03F953000204|288A||0000 <br><br>            If this is encrypted using e2ee Library: <br>            htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY             u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3             jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb             oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr            9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
  "shipping_address": {
    "street": "1 Main St.",
    "street2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "country": "US",
    "postal_code": "85284",
    "county": "Oakland"
  },
  "shipping_name": "Steve Smith",
  "tax_amount": "2.16",
  "discretionary_data": [
    {
      "disc_id": 0,
      "value": "string"
    }
  ],
  "surcharge_info": { }
}
```

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

### Encrypt Data using OpenSSL CLI

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

This example demonstrates how to encrypt data using OpenSSL command-line tools. It fetches the public key and then encrypts a given input string using RSA-OAEP padding and base64 encoding. Ensure the DOMAIN variable is adjusted for sandbox or production environments.

```bash
$DOMAIN='https://api.sandbox.paytrace.com/v3' # Adjust to sandbox as needed
CIPHERTEXT=$(openssl pkeyutl               -encrypt               -inkey <(curl -s "$DOMAIN"/e2ee/public-key.pem | jq -r .data)             CIPHERTEXT=$(openssl pkeyutl \
  -encrypt \
  -inkey <(curl -s "$DOMAIN"/e2ee/public-key.pem | jq -r .data) \
  -pkeyopt rsa_padding_mode:oaep \
  -pubin -in <(echo -n "$INPUT") | base64 | tr -d'\n')

```

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

### Fetch Customer Record (with X-Permalinks)

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Example of fetching a customer record using the X-Permalinks header. This allows for immutable record retrieval.

```http
GET :url/customer/50f55406-83e5-4032-a743-c3051a933e2d
Authorization: Bearer <token>
X-Permalinks: true
```

```http
GET :url/customer/87654321
Authorization: Bearer <token>
X-Permalinks: true
```

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

### Determine Card Type for Level 3 Data

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Applications should identify the card type (Visa or MasterCard) before formatting Level 3 data requests. Visa card numbers start with '4', and MasterCard numbers start with '5' or '2' (for cards issued from 2017 onwards).

```plaintext
Visa and MasterCard have their own requirements for level 3 data,
so your application should be able to determine if the transaction being
updated is with a Visa or a MasterCard before formatting and sending the request.

All Visa account numbers begin with “4” and all MasterCard account numbers
begin with “5”.

In order to issue more cards, MasterCard is beginning to issue cards
beginning with a "2" in 2017.

```

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

### POST /v3/checkout/setting 201 Response Sample

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Example JSON response for a successful creation or update of checkout settings. Includes the newly generated or updated setting ID.

```json
{
  "silent_post": "https://example.com/payment-response",
  "terms_conditions_link": "http://example.com/terms-redirect-link",
  "payment_approved_link": "http://example.com/payment-approved-link",
  "payment_declined_link": "http://example.com/payment-declined-link",
  "return_method": "HYPERLINK",
  "email_required": true,
  "billing_address_required": true,
  "csc_required": true,
  "merchant_id": 12345,
  "user": "nick",
  "invoice_expiration_days": 14,
  "id": 246810

}
```

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

### Fetch Customer Record With X-Permalinks (ID)

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Use this example when fetching a customer record with the X-Permalinks header, using the customer_id. The header ensures immutable record retrieval.

```http
GET :url/customer/87654321
Authorization: Bearer <token>
X-Permalinks: true
```

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

### Get Checkout URL

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Retrieves the checkout URL for a given invoice ID.

```APIDOC
## GET /v3/invoice/{invoice_id}

### Description
Retrieves the checkout URL associated with a specific invoice ID. This endpoint is useful for redirecting customers to an existing payment page.

### Method
GET

### Endpoint
/v3/invoice/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The unique identifier of the invoice for which to retrieve the checkout URL.

### Authorization
BearerAuth
```

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

### Get Checkout Design

Source: https://api.sandbox.paytrace.com/v3/redoc#tag/Introduction

Retrieves a specific checkout design configuration by its ID.

```APIDOC
## GET /v3/checkout/design/{design_id}

### Description
Retrieves a specific checkout design configuration by its ID.

### Method
GET

### Endpoint
https://api.sandbox.paytrace.com/v3/checkout/design/{design_id}

### Parameters
#### Path Parameters
- **design_id** (integer) - Required - The unique identifier for the checkout design.

#### Header Parameters
- **X-Integrator-Id** (string) - Optional - A unique ID to correlate an API consumer's calls to the PayTrace system. Maximum length: 12 characters.
- **X-Permalinks** (string) - Optional - Including a "truthy" value (valid values: `true`, `y`, `yes`, `1`) will ensure any records returned include an immutable `uuid` key. This is useful for retaining external records.

### Responses
#### Success Response (200)
- **id** (integer) - The unique identifier for the checkout design.
- **merchant_id** (integer) - The unique system identifier for the merchant account.
- **checkout_style** (string) - The visual layout template applied to the checkout interface.
- **company_logo** (string) - The brand's logo as a Base64 encoded Data URI.
- **selected_color_theme** (string) - The primary brand color.
- **font** (string) - The font family name.
- **font_color** (string) - The hexadecimal code for general text content.
- **button_text_color** (string) - The hexadecimal code for text appearing inside action buttons.
- **input_field_style** (string) - The border and corner styling for form inputs.

#### Validation Error (422)
Details about validation errors.
```