# Low Code JS
Source: https://docs.fractalpay.com/EmbeddedPayments

Fractal JS in depth

Welcome to the Widgets API documentation. This API allows you to integrate and interact with various payment widgets seamlessly. You can embed buttons for payments, request payments, and display transaction tables.

### Widget Usage

### Pay Link

**Pay Button**

HTML implementation

```html theme={null}
<a href="javascript:void(0);" onclick="getPaymentPage(8)" class="btn btn-primary">Pay</a>
```

React/Vue js implementation

```java theme={null}
import { GetPaymentPage } from 'fractalpay';
```

**Description**: This widget generates a button that, when clicked, opens a payment page for the amount `8.00`.

**Parameters**:

* `amount` (number): The amount of the widget to open the payment page for.

**Example**:

```html theme={null}
<a href="javascript:void(0);" onclick="getPaymentPage(8.00)" class="btn btn-primary">Pay</a>
```

```html theme={null}
  <GetPaymentPage fractalpayClientKey={fractalpayClientKey} amount={8.55} />
```

### Request Link

**Request Payment Button**

HTML implementation

```html theme={null}
<a href="javascript:void(0);" onclick="sendRequestPayment(8.00, '9695969889')" class="btn btn-primary">Request payment</a>
```

React/Vue js implementation

```java theme={null}
import { RequestPaymentonClick } from 'fractalpay';
```

**Description**: This widget generates a button that, when clicked, sends a payment request to the specified phone number for the amount of `8.00`.

**Parameters**:

* `amount` (number): The value of the widget to send the payment request for.
* `recipient_phone` (string): The phone number of the recipient.

**Example**:

```html theme={null}
<a href="javascript:void(0);" onclick="sendRequestPayment(8.00, '9695969889')" class="btn btn-primary">Request payment</a>
```

React/Vue js

```html theme={null}
  <RequestPaymentonClick fractalpayClientKey={fractalpayClientKey} amount={invoice.amount} phone_number={phoneNumbers[invoice.id] || ""}/>
```

### Transactions Table

**Transactions Table**

HTML implementation

```html theme={null}
<table id="fractal_complete_transactions" class="table"></table>
```

React/Vue js implementation

```java theme={null}
import { CompletedTransactions } from 'fractalpay';
```

**Description**: This widget generates a table to display complete transactions.

**Parameters**:

* `id` (string): The ID of the table element. In this case, it is `fractal_complete_transactions`.

**Example**:

```html theme={null}
<table id="fractal_complete_transactions" class="table"></table>
```

React/Vue.js

```html theme={null}
<CompletedTransactions fractalpayClientKey={fractalpayClientKey}/>
```

### Installing JS & NPM Package

To use these widgets, include the following script tag in your HTML:

```html theme={null}
<script src="https://testapi.fractalpay.com/js/dynamic-launch.js?fractalpay_merchant_public_key={{merchant_public_key}}"></script>
```

Replace `{{merchant_public_key}}` with your actual merchant public key.

To use these widgets in a react/Vue.js app, install the following npm package:

```java theme={null}
npm i fractal-pay-now
```

To use the components in a react/Vue.js app, use the below line to import the proper npm function:

```java theme={null}
import { --flag-- } from 'fractalpay';
```

### Error Handling and FAQs

### Error Handling

**Error Codes:**

* **400 Bad Request**: The request was invalid or cannot be otherwise served.
* **401 Unauthorized**: Authentication is required and has failed or has not yet been provided.
* **404 Not Found**: The requested resource could not be found.
* **500 Internal Server Error**: An error occurred on the server.

### FAQs and Troubleshooting

* **Q: What should I do if I receive a 401 Unauthorized error?**
  **A:** Ensure that your API key is correct and included in the request header.

* **Q: How do I update the settings of a widget?**
  **A:** Use the PUT /widgets/ endpoint with the new settings in the request body.


# Webhooks
Source: https://docs.fractalpay.com/Webhooks



# Webhook Events

This page documents the various webhook events that can be triggered by the Payrix platform. Webhooks are used to notify your application when specific events occur.

## Table of Contents

1. [Payment Success](#payment-success)
2. [Merchant Onboarding](#merchant-onboarding)
3. [Merchant Approval](#merchant-approval)
4. [Documents Signed](#documents-signed)
5. [ACH Update](#ach-update)
6. [Void from EasyPay](#void-from-easypay)
7. [Partial Refund](#partial-refund)
8. [Payment Request (Preauth)](#payment-request-preauth)
9. [Pre-Authorization Update](#pre-authorization-update)
10. [Capture Pre-Authorization](#capture-pre-authorization)

## Payment Success

### Event: `payment.success`

#### Description

This event is triggered when a payment is successfully processed.

#### Payload Example

```json theme={null}
{
    "event_type": "payment.success",
    "data": {
        "transaction_id": "txn_a7f0b5340a",
        "merchant_id": "m_xxxxxxxxxx",
        "amount": 1.00,
        "net_amount": 0.95,
        "fee_amount": 0.05,
        "order_id": "example-order-id",
        "last_four": "0043",
        "brand": "VISA",
        "link_id": ""
    }
}
```

#### Explanation

* `transaction_id`: Unique identifier for the transaction.
* `merchant_id`: Unique identifier for the merchant.
* `amount`: Total amount of the payment.
* `net_amount`: Amount received after fees.
* `fee_amount`: Fee amount charged for the transaction.
* `order_id`: Identifier for the associated order.
* `last_four`: Last four digits of the card used.
* `brand`: Card brand (e.g. VISA, Mastercard).
* `link_id`: Associated pay link ID, if applicable.

## Merchant Onboarding

### Event: `merchant.onboarding`

#### Description

This event is triggered when a merchant completes the onboarding process.

#### Payload Example

```json theme={null}
{
    "event_type": "merchant.onboarding",
    "data": {
        "merchant_key": "example-merchant-api-key",
        "merchant_id": "m_xxxxxxxxxx",
        "business_name": "Example Business",
        "email": "merchant@example.com",
        "public_key": "example-public-key"
    }
}
```

#### Explanation

* `merchant_key`: Unique key assigned to the merchant.
* `merchant_id`: Unique identifier for the merchant.
* `business_name`: Name of the merchant's business.
* `email`: Merchant's contact email.
* `public_key`: Public key associated with the merchant.

## Merchant Approval

### Event: `merchant.approval`

#### Description

This event is triggered when a merchant's application is approved.

#### Payload Example

```json theme={null}
{
    "event_type": "merchant.approval",
    "data": {
        "merchant_id": "m_xxxxxxxxxx",
        "business_name": "Example Business",
        "email": "merchant@example.com",
        "company_id": "example-company-id"
    }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `business_name`: Name of the merchant's business.
* `email`: Merchant's contact email.
* `company_id`: Unique identifier for the associated company.

### Testing Merchant Approval Webhooks in Sandbox

This guide walks through how to mock a merchant approval event in the sandbox environment to verify your webhook integration before going live.

<Note>The mock approval endpoint is sandbox-only and will return an error if called in production.</Note>

#### Step 1: Set Up a Webhook Receiver

If you don't already have a server endpoint ready to receive webhooks, use [webhook.site](https://webhook.site) to get a temporary public URL that logs all incoming requests. Copy the unique URL it generates — you'll use it in Step 2.

#### Step 2: Register Your Webhook URL

Register the URL where Fractal should send webhook events. This replaces any previously registered URL for your client account.

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "message": "Webhook url updated successfully"
}
```

#### Step 3: Trigger a Mock Merchant Approval

Send a POST request with the merchant's GUID as `merchant_id`. This fires a `merchant.approval` webhook to your registered URL immediately.

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/approve-merchant \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "m_xxxxxxxxxx"
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "message": "Webhook dispatch started"
}
```

#### Step 4: Verify the Webhook Payload

Your registered endpoint will receive a POST request with the following payload:

```json theme={null}
{
  "event_type": "merchant.approval",
  "data": {
    "merchant_id": "m_xxxxxxxxxx",
    "business_name": "Example Business",
    "email": "merchant@example.com",
    "company_id": "example-company-id"
  }
}
```

This matches the payload your integration will receive when a merchant's application is approved.

#### Finding Your merchant\_id

The `merchant_id` is the merchant's GUID — not the API key. It can be found in the Fractal dashboard or from the response when the merchant was originally onboarded.

## Documents Signed

### Event: `documents.signed`

#### Description

This event is triggered when a merchant completes signing the required documents.

#### Payload Example

```json theme={null}
{
    "event_type": "documents.signed",
    "data": {
        "merchant_id": "m_xxxxxxxxxx",
        "business_name": "Example Business",
        "website": "https://example.com",
        "email": "merchant@example.com",
        "company_id": "example-company-id"
    }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `business_name`: Name of the merchant's business.
* `website`: Merchant's website URL.
* `email`: Merchant's contact email.
* `company_id`: Unique identifier for the associated company.

## ACH Update

### Event: `ach.update`

#### Description

This event is triggered when an ACH transaction status changes — either approved or declined.

#### Payload Example

```json theme={null}
{
  "event_type": "ach.update",
  "data": {
    "merchant_id": "m_xxxxxxxxxx",
    "status": "Approved",
    "tran_id": "txn_xxxxxxxx",
    "message": "Approved"
  }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `status`: `Approved` or `Declined`.
* `tran_id`: The original ACH transaction ID.
* `message`: `Approved` or `Insufficient Funds`.
* `return_transaction_id`: ID of the reversal record — only present on `Declined`.

### Testing ACH Update Webhooks in Sandbox

This guide walks through how to mock an ACH payment status update in the sandbox environment to verify your webhook integration.

<Note>The mock ACH update endpoint is sandbox-only and will return an error if called in production.</Note>

#### Prerequisites

Before testing you'll need:

* A merchant under your client account that has at least one ACH transaction in the system
* Your webhook URL registered (see the Merchant Approval Webhook guide for setup steps — same endpoint)

#### Step 1: Register Your Webhook URL

If not already set up from a previous test:

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

#### Step 2: Trigger a Mock ACH Approval

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/update-ach \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_xxxxxxxx",
    "new_status": "approved"
  }'
```

**Response:**

```json theme={null}
{ "result": true, "message": "Success." }
```

**Webhook payload received:**

```json theme={null}
{
  "event_type": "ach.update",
  "data": {
    "merchant_id": "m_xxxxxxxxxx",
    "status": "Approved",
    "tran_id": "txn_xxxxxxxx",
    "message": "Approved"
  }
}
```

#### Step 3: Trigger a Mock ACH Decline

Same endpoint, `new_status` set to `"declined"`:

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/update-ach \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_xxxxxxxx",
    "new_status": "declined"
  }'
```

**Webhook payload received:**

```json theme={null}
{
  "event_type": "ach.update",
  "data": {
    "merchant_id": "m_xxxxxxxxxx",
    "status": "Declined",
    "tran_id": "txn_xxxxxxxx",
    "message": "Insufficient Funds",
    "return_transaction_id": "txn_yyyyyyyyyy"
  }
}
```

`return_transaction_id` is the ID of the reversal record created when an ACH is declined.

#### Finding a Valid transaction\_id

The `transaction_id` must be the `pos_guid` of an existing ACH transaction for the merchant. Only `approved` and `declined` are valid values for `new_status` — anything else returns a 400.

## Void from EasyPay

### Event: `payment.void`

#### Description

This event is triggered when a transaction is successfully voided.

#### Payload Example

```json theme={null}
{
  "event_type": "payment.void",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "transaction_id": "txn_454e460495",
    "Status": "Success",
    "linked_txn_id": "txn_c3b9865e78",
    "sales_id": "txn_454e460495",
    "order_createdfrom": "API",
    "amount": 2,
    "txn_id": "txn_Y9tiwFkMbv9vcHHwAZVE",
    "txn_date": "2026-06-15T16:31:44.000Z",
    "type": "Void"
  }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `transaction_id`: ID of the void transaction record created.
* `Status`: `Success` or `Error`.
* `linked_txn_id`: ID of the original transaction that was voided.
* `sales_id`: Same as `transaction_id` — the void record ID.
* `order_createdfrom`: Source of the original order (e.g. `API`).
* `amount`: Amount voided.
* `txn_id`: Gateway-level transaction reference ID.
* `txn_date`: Timestamp of the void.
* `type`: Always `Void`.

### Testing in Sandbox

#### Step 1: Register your webhook URL (skip if already done)

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

#### Step 2: Trigger a void

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/order/sales-void \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_xxxxxxxx",
    "amount": "2.00"
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Transaction voided successfully",
  "data": {
    "sales_id": "txn_454e460495",
    "order_createdfrom": "API",
    "amount": 2,
    "txn_id": "txn_Y9tiwFkMbv9vcHHwAZVE",
    "txn_date": "2026-06-15T16:31:44.000Z",
    "linked_txn_id": "txn_c3b9865e78",
    "transaction_id": "txn_454e460495",
    "Status": "Success",
    "type": "Void"
  }
}
```

<Note>The transaction must be voided before it settles. A settled transaction returns `"The transaction has been settled, a void is not allowed."` Use a transaction created the same day for sandbox testing.</Note>

## Partial Refund

### Event: `payment.refund`

#### Description

This event is triggered when a refund is successfully processed on a completed card transaction.

#### Payload Example

```json theme={null}
{
  "event_type": "payment.refund",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "transaction_id": "txn_a8f83189a5",
    "Status": "Success",
    "linked_txn_id": "txn_a8f83189a5",
    "parent_transaction_id": "txn_b65f37d127",
    "sales_id": "txn_a8f83189a5",
    "order_createdfrom": "API",
    "amount": 1,
    "txn_id": "txn_lyWexIP9z2MJkrBBtscY",
    "txn_date": "2026-06-15T19:13:03.000Z",
    "type": "Refund"
  }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `transaction_id`: ID of the new refund record created.
* `Status`: `Success`.
* `linked_txn_id`: Same as `transaction_id` — the refund record ID.
* `parent_transaction_id`: The original transaction that was refunded.
* `sales_id`: Same as `transaction_id`.
* `order_createdfrom`: Source of the original order (e.g. `API`).
* `amount`: Refund amount (positive decimal).
* `txn_id`: Gateway-level transaction reference ID.
* `txn_date`: ISO 8601 timestamp of the refund.
* `type`: Always `Refund`.

### How to Issue a Refund

**Endpoint:** `POST /api/v1/order/sales-return`
**Auth:** Basic Auth (`client_id:secret_key`)

#### Request Parameters

| Field            | Type   | Required | Description                                                                     |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `merchant_key`   | string | Yes      | Merchant API key                                                                |
| `transaction_id` | string | Yes      | `pos_guid` of the original completed transaction                                |
| `amount`         | string | Yes      | Amount to refund — must not exceed the original or remaining refundable balance |

#### Step 1: Register your webhook URL (skip if already done)

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "message": "Webhook url updated successfully"
}
```

#### Step 2: Issue the refund

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/order/sales-return \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_xxxxxxxx",
    "amount": "1.00"
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Transaction refunded successfully",
  "data": {
    "sales_id": "txn_a8f83189a5",
    "order_createdfrom": "API",
    "amount": 1,
    "txn_id": "txn_lyWexIP9z2MJkrBBtscY",
    "txn_date": "2026-06-15T19:13:03.000Z",
    "linked_txn_id": "txn_xxxxxxxx",
    "transaction_id": "txn_a8f83189a5",
    "Status": "Success",
    "type": "Refund"
  }
}
```

#### Step 3: Verify the webhook payload

Your registered endpoint will receive a POST request with the following payload:

```json theme={null}
{
  "event_type": "payment.refund",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "transaction_id": "txn_a8f83189a5",
    "Status": "Success",
    "linked_txn_id": "txn_a8f83189a5",
    "parent_transaction_id": "txn_xxxxxxxx",
    "sales_id": "txn_a8f83189a5",
    "order_createdfrom": "API",
    "amount": 1,
    "txn_id": "txn_lyWexIP9z2MJkrBBtscY",
    "txn_date": "2026-06-15T19:13:03.000Z",
    "type": "Refund"
  }
}
```

Use `parent_transaction_id` to trace back to the original charge.

#### Error responses

| Scenario                                    | Message                                                         |
| ------------------------------------------- | --------------------------------------------------------------- |
| Transaction not found or not completed      | `"Payment method not found."`                                   |
| Amount exceeds original transaction         | `"Amount should not be greater than sales charge amount."`      |
| Amount exceeds remaining refundable balance | `"The amount should not be greater than the remaining amount."` |
| Transaction already fully refunded          | `"Refund already done. No refund allowed."`                     |

<Note>Partial refunds can be issued multiple times against the same transaction as long as the cumulative total does not exceed the original charge amount. If the refund amount equals the full transaction amount and the transaction is older than 24 hours, the API automatically performs a void instead.</Note>

## Payment Request (Preauth)

### Event: `preauth`

#### Description

This event is triggered when a customer successfully completes a preauthorization via a payment request link. The customer's card is authorized for the amount but not charged until you explicitly capture the preauth.

#### Flow

1. Your server calls `POST /api/v1/requests` with `preauth: true` — returns a `pay_link`
2. You send the `pay_link` to your customer (or the API sends it via SMS/email automatically)
3. The customer visits the link and enters their card details to authorize
4. On successful authorization → your registered webhook URL receives the `preauth` event

#### Payload Example

```json theme={null}
{
  "event_type": "preauth",
  "data": {
    "merchant_id": "m_f2d5caadab",
    "guid": "txn_b71af1a75f",
    "amount": 10,
    "order_id": "5467",
    "customer_id": 0
  }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `guid`: Transaction ID of the preauthorization record.
* `amount`: Amount that was preauthorized.
* `order_id`: The order reference you provided in the original request.
* `customer_id`: Internal customer ID, or `0` if no customer profile was linked.

### How to Create a Payment Request

**Endpoint:** `POST /api/v1/requests`
**Auth:** Basic Auth (`client_id:secret_key`)

#### Request Parameters

| Field              | Type    | Required | Description                                                   |
| ------------------ | ------- | -------- | ------------------------------------------------------------- |
| `merchant_key`     | string  | Yes      | Merchant API key                                              |
| `amount`           | string  | Yes      | Payment amount                                                |
| `order_id`         | string  | Yes      | Your unique order reference (max 100 characters)              |
| `phone_number`     | string  | No       | Customer phone — triggers SMS with pay link                   |
| `email`            | string  | No       | Customer email — triggers email with pay link                 |
| `name`             | string  | No       | Customer name, used in the email template                     |
| `preauth`          | boolean | No       | Set to `true` to issue a preauthorization instead of a charge |
| `pass_fee`         | boolean | No       | Pass the processing fee to the customer                       |
| `require_3ds`      | boolean | No       | Require 3D Secure authentication                              |
| `allow_card`       | boolean | No       | Allow card payment (default: `true`)                          |
| `allow_ach`        | boolean | No       | Allow ACH payment (default: `true`)                           |
| `invoice_number`   | string  | No       | Invoice reference (alphanumeric, max 100 characters)          |
| `sub_merchant_key` | string  | No       | Sub-merchant key, if applicable                               |

#### Step 1: Register your webhook URL (skip if already done)

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

#### Step 2: Create the payment request

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/requests \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "amount": "10.00",
    "order_id": "5467",
    "phone_number": "7777771234",
    "email": "customer@example.com",
    "preauth": true,
    "pass_fee": true,
    "require_3ds": false,
    "invoice_number": "345",
    "allow_card": true,
    "allow_ach": true
  }'
```

**Response:**

```json theme={null}
{
  "message": "Authorization request has been sent",
  "data": {
    "order_id": "5467",
    "link_id": "gsgqll4xfa7",
    "pay_link": "https://testapi.fractalpay.com/authcheck-paymentlink/gsgqll4xfa7"
  }
}
```

#### Step 3: Customer completes preauth

Share the `pay_link` with your customer (or the API will send it automatically if `phone_number` or `email` was provided). When the customer authorizes, your webhook endpoint receives the `preauth` event.

#### Step 4: Verify the webhook payload

```json theme={null}
{
  "event_type": "preauth",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "guid": "txn_b71af1a75f",
    "amount": 10,
    "order_id": "5467",
    "customer_id": 0
  }
}
```

Use the `guid` to capture or void the preauth via the `/preauth/capture` or `/preauth/void` endpoints.

<Note>At least one of `allow_card` or `allow_ach` must be `true`. If `phone_number` or `email` is provided, the API automatically sends the pay link — you do not need to deliver it manually.</Note>

<Note>Partial refunds can be issued multiple times against the same transaction as long as the cumulative total does not exceed the original charge amount. If the refund amount equals the full transaction amount and the transaction is older than 24 hours, the API automatically performs a void instead.</Note>

## Pre-Authorization Update

### Events: `preauth.increment` / `preauth.decrement`

#### Description

These events are triggered when the authorized amount on an existing preauthorization is changed. The same endpoint handles both directions — the direction is determined by comparing `new_authorized_amount` to `last_authorized_amount`.

| Condition                                           | Event fired         |
| --------------------------------------------------- | ------------------- |
| `new_authorized_amount` > `last_authorized_amount`  | `preauth.increment` |
| `new_authorized_amount` \< `last_authorized_amount` | `preauth.decrement` |

#### Payload Example

```json theme={null}
{
  "event_type": "preauth.increment",
  "data": {
    "merchant_id": "m_f2d5caadab",
    "guid": "txn_f84144f73a",
    "amount": "11.00",
    "order_id": "5467",
    "customer_id": 0
  }
}
```

The `preauth.decrement` payload has the same shape — only `event_type` and `amount` differ.

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `guid`: Transaction ID of the preauthorization record.
* `amount`: The new authorized amount after the update.
* `order_id`: The order reference associated with the preauth.
* `customer_id`: Internal customer ID, or `0` if no customer profile was linked.

### How to Update a Pre-Authorization

**Endpoint:** `POST /api/v1/preauth/update`
**Auth:** Basic Auth (`client_id:secret_key`)

#### Request Parameters

| Field                    | Type   | Required | Description                                                  |
| ------------------------ | ------ | -------- | ------------------------------------------------------------ |
| `merchant_key`           | string | Yes      | Merchant API key                                             |
| `transaction_id`         | string | Yes      | `guid` of the existing preauthorization                      |
| `last_authorized_amount` | string | Yes      | Current authorized amount — must match the amount on record  |
| `new_authorized_amount`  | string | Yes      | Target authorized amount — determines increment or decrement |
| `order_id`               | string | No       | Your order reference                                         |

#### Step 1: Register your webhook URL (skip if already done)

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

#### Step 2: Submit the update

**Increment (raise the authorization):**

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/preauth/update \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_77c9a625a3",
    "last_authorized_amount": "10.00",
    "new_authorized_amount": "11.00",
    "order_id": "5467"
  }'
```

**Decrement (partial reversal):** same endpoint, `new_authorized_amount` less than `last_authorized_amount`.

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Amount Updated Successfully",
  "data": {
    "Status": "Approved",
    "Account": "0043",
    "Brand": "Visa",
    "AuthCode": "",
    "Authorized": "11.00",
    "transaction_id": "txn_77c9a625a3",
    "orderid": "5467"
  }
}
```

#### Step 3: Verify the webhook payload

```json theme={null}
{
  "event_type": "preauth.increment",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "guid": "txn_xxxxxxxx",
    "amount": "11.00",
    "order_id": "5467",
    "customer_id": 0
  }
}
```

#### Error responses

| Scenario                                              | Message                                                       |
| ----------------------------------------------------- | ------------------------------------------------------------- |
| `last_authorized_amount` doesn't match current record | `"Amount mismatch"`                                           |
| Trying to increment an already-decremented auth       | `"Authorization can only be decreased, captured, or voided."` |
| Trying to decrement an already-incremented auth       | `"Authorization can only be increased, captured, or voided."` |
| Preauth not found                                     | `"Authorization not found"`                                   |

<Note>The `last_authorized_amount` must exactly match the current authorized amount stored on the preauthorization record. If the amount has changed since you last queried it, the request will return an `"Amount mismatch"` error.</Note>

## Capture Pre-Authorization

### Event: `preauth.charge`

#### Description

This event is triggered when a preauthorization is successfully captured — the customer's card is charged for the authorized amount and the preauth is converted into a completed transaction.

#### Payload Example

```json theme={null}
{
  "event_type": "preauth.charge",
  "data": {
    "merchant_id": "m_f2d5caadab",
    "link_id": "txn_f84144f73a",
    "guid": "txn_77c9a625a3",
    "amount": "11.00",
    "order_id": "5467",
    "net_amount": 10.64
  }
}
```

#### Explanation

* `merchant_id`: Unique identifier for the merchant.
* `link_id`: The preauthorization transaction ID that was captured (the `transaction_id` you passed in the request).
* `guid`: The resulting completed transaction ID created by the capture.
* `amount`: Amount that was captured.
* `order_id`: The order reference associated with the preauth.
* `net_amount`: Amount received after fees.

### How to Capture a Pre-Authorization

**Endpoint:** `POST /api/v1/preauth/capture`
**Auth:** Basic Auth (`client_id:secret_key`)

#### Request Parameters

| Field            | Type   | Required | Description                               |
| ---------------- | ------ | -------- | ----------------------------------------- |
| `merchant_key`   | string | Yes      | Merchant API key                          |
| `transaction_id` | string | Yes      | `guid` of the preauthorization to capture |

#### Step 1: Register your webhook URL (skip if already done)

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/client/update-webhooks-url \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-endpoint.com/webhook"
  }'
```

#### Step 2: Capture the preauthorization

```bash theme={null}
curl -X POST https://testapi.fractalpay.com/api/v1/preauth/capture \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "your-merchant-api-key",
    "transaction_id": "txn_f84144f73a"
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Payment captured successfully.",
  "data": {
    "Status": "Approved",
    "Account": "0043",
    "Brand": "Visa",
    "AuthCode": "",
    "amount": "11.00",
    "Authorized": 11,
    "orderid": "5467",
    "transaction_id": "txn_77c9a625a3",
    "net_amount": 10.64
  }
}
```

#### Step 3: Verify the webhook payload

```json theme={null}
{
  "event_type": "preauth.charge",
  "data": {
    "merchant_id": "m_xxxxxxxx",
    "link_id": "txn_f84144f73a",
    "guid": "txn_77c9a625a3",
    "amount": "11.00",
    "order_id": "5467",
    "net_amount": 10.64
  }
}
```

Note that `link_id` is the preauth `transaction_id` you passed in — use it to correlate the capture back to the original preauth. `guid` is the new completed transaction ID.

#### Error responses

| Scenario          | Message                     |
| ----------------- | --------------------------- |
| Preauth not found | `"Authorization not found"` |

<Note>The `last_authorized_amount` must exactly match the current authorized amount stored on the preauthorization record. If the amount has changed since you last queried it, the request will return an `"Amount mismatch"` error.</Note>


# Charge Customer
Source: https://docs.fractalpay.com/api-reference/customers/charge-customer

post /customers/charge/{customerId}
Charge Customer



# Create Customer
Source: https://docs.fractalpay.com/api-reference/customers/create-customer

post /customers/add
Create Customer



# Get Customer
Source: https://docs.fractalpay.com/api-reference/customers/get-customer

get /customers/{customerId}
Get Customer



# Get Customers
Source: https://docs.fractalpay.com/api-reference/customers/get-customers

get /customers
Get Customers



# Request Card
Source: https://docs.fractalpay.com/api-reference/customers/request-card

post /customers/request-card/{customerId}
Request Card



# Full Merchant Submit
Source: https://docs.fractalpay.com/api-reference/merchant-onboarding/full-merchant-submit

post /onboarding
Full Merchant Submit



# Get Merchants by Client
Source: https://docs.fractalpay.com/api-reference/merchant-onboarding/get-merchants-by-client

get /merchant
Get Merchants by Client



# Hosted Onboarding
Source: https://docs.fractalpay.com/api-reference/merchant-onboarding/hosted-onboarding

SAML authentication and hosted merchant onboarding flow

# Fractal SAML Authentication & Onboarding

Steps for integrating Fractal SAML authentication and launching the hosted onboarding flow.

All endpoints require Basic Auth on every request:

* **Username** = Client ID
* **Password** = Secret Key

***

## Step 1: Create a Session

Call the create-session endpoint to authenticate and receive a session token. Optionally pass `?is_publickey=true` to also retrieve your client's shared public key.

```bash theme={null}
curl -X GET 'https://{baseURL}/api/v1/auth/create-session' \
  -u "{client_id}:{secret_key}"
```

To also fetch your public key:

```bash theme={null}
curl -X GET 'https://{baseURL}/api/v1/auth/create-session?is_publickey=true' \
  -u "{client_id}:{secret_key}"
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "SAML authentication successful",
  "data": {
    "sessionToken": "<session_token>",
    "public_key": "<your_public_key>"
  }
}
```

Store the `sessionToken` — it is required in Step 2.

***

## Step 2: Initiate the Hosted Onboarding Form

Pass the `session_token` from Step 1 as a URL parameter. The body fields are optional — include any merchant data you have available.

```bash theme={null}
curl -X POST 'https://{baseURL}/api/v1/auth/onboarding/{session_token}' \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "{internal_company_id}",
    "BusinessInfo": {
      "business_name": "Test Pay LLC",
      "business_email": "test@example.com",
      "business_phone": "5551234567",
      "business_address": "123 Main Street",
      "business_city": "Austin",
      "business_state": "TX",
      "business_zip": "78701",
      "business_country": "US"
    }
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Merchant onboarding successfully",
  "data": {
    "merchant_id": "<merchant_id>",
    "company_id": "<your_company_id>",
    "onboarding_link": "<one_time_onboarding_url>"
  }
}
```

The `onboarding_link` is a one-time URL to send to the merchant to complete the form. Store the `merchant_id` — it is required for future API calls.

***

## Step 3: Merchant Completes the Onboarding Form

Send the `onboarding_link` from Step 2 to the merchant. When they open the link, they will be presented with a hosted onboarding form to complete their business and banking details.

The link is **one-time use** — it expires once submitted or after a set period. Once the merchant submits the form, their application will move into a pending review state.

***

## Step 4: Check Merchant Status

Once the merchant submits the onboarding form, use this endpoint to poll their approval status.

The `merchant_key` here is the merchant's **Fractal API key** — found in their Fractal dashboard. This is distinct from the `merchant_id` (the `m_` prefixed GUID) and the `public_key` returned by the merchant list endpoint.

```bash theme={null}
curl -X POST 'https://{baseURL}/api/v1/auth/get-onboarding-status' \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "{fractal_api_key}"
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "merchant status found",
  "data": {
    "merchantStatus": "pending"
  }
}
```

`merchantStatus` will be either `"pending"` or `"completed"`. You can also use webhooks to track `merchant_status` for real-time updates instead of polling.


# Create Link
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/create-payment-link

post /pay-link
Create Link



# Delete Pay Link
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/delete-pay-link

delete /pay-link/{linkId}
Delete Pay Link



# Payment Request
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/payment-request

post /requests
Payment Request



# Payment Request Customer
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/payment-request-customer

post /requests/{customerId}
Payment Request Customer



# Payment Link
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/qr-payment-link

post /order/api-qr_code_link
Payment Link



# Remote Deposit Capture
Source: https://docs.fractalpay.com/api-reference/payment-collection-methods/remote-deposit-capture

post /merchant/remote_deposit_capture
Submit a check image for remote deposit capture. Sends the front and back images of a check as a multipart/form-data upload.

**Note:** The merchant must have Skyfi ACH credentials configured — requests will fail with `"Skyfi merchant or account detail not found"` if credentials are not set up.



# Capture Pre-Authorization
Source: https://docs.fractalpay.com/api-reference/preauthorizations/capture-pre-authorization

post /preauth/capture
Charges the customer for the currently authorized amount on an existing preauthorization. Converts the preauth into a completed transaction. Fires a preauth.charge webhook on success.



# Update Pre-Authorization
Source: https://docs.fractalpay.com/api-reference/preauthorizations/increment-pre-authorization

post /preauth/update
Increases or decreases the authorized amount on an existing preauthorization. If new_authorized_amount is greater than last_authorized_amount, an incremental authorization is issued and a preauth.increment webhook fires. If new_authorized_amount is less, a partial reversal is issued and a preauth.decrement webhook fires. last_authorized_amount must match the current authorized amount on the record.



# Get Transaction
Source: https://docs.fractalpay.com/api-reference/transactions/get-transaction

get /merchant/transactions/{transaction_id}
Get Transaction



# Get Transactions
Source: https://docs.fractalpay.com/api-reference/transactions/get-transactions

get /merchant/transactions
Get Transactions



# Return Sale
Source: https://docs.fractalpay.com/api-reference/transactions/return-sale

post /order/sales-return
Return Sale



# Void Sale
Source: https://docs.fractalpay.com/api-reference/transactions/void-sale

post /order/sales-void
Void Sale



# GooglePay™ Web Integration
Source: https://docs.fractalpay.com/googlepay



### Add Google Pay to your application (Web)

Reach out to your Fractal point of contact to obtain a `FRACTAL_GATEWAY_MERCHANT_ID`

Follow the [Google Pay Web developer documentation](https://developers.google.com/pay/api/web)
to integrate Google Pay into your website.

### Tokenization Specification

Use the following values in the the TokenizationSpecification:

```json theme={null}
{
    "gateway": "fractal"
    "gatewayMerchantId": FRACTAL_GATEWAY_MERCHANT_ID
}
```

### Supported Authentication Methods

* PAN\_ONLY
* CRYPTOGRAM\_3DS

### Supported Card Networks

* Amex
* MasterCard
* Discover
* Visa

## Obtain a Production Merchant ID from Google

Ensure that you follow the [Google Pay Web brand guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines)
and complete all items on the
[Google Pay Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist).

Follow [these instructions](https://developers.google.com/pay/api/web/guides/test-and-deploy/publish-your-integration)
to publish Google Pay integeration and receive a merchant ID that can be used in the production environment.

## Send the Google Pay token in the Preauth API

The Google Pay API response is a [PaymentData](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) object.
The field containing the encrypted payment information is `paymentMethodData.tokenizationData.token`

This token should be sent in the [/preauth](/api-reference/preauthorizations/pre-authorization-with-token) request

```json theme={null}
{
    "Token": {
        "type": "google_pay",
        "data": GOOGLE_PAY_TOKEN
    },
    ...
}
```


# Implementation Guide
Source: https://docs.fractalpay.com/implementationguide

Integrations simplified

# Implementation Guide

Information for partners who will integrate Fractal's features into their apps.

This guide provides partners with all the information to set up, test, and launch Fractal integration as part of their application. This process includes four main phases:

1. [Creating an SOW](#pre-implementation) - Work with Fractal to create a Scope of Work describing your integration and identifying requirements across the Fractal Platform.
2. [Sandbox Setup](#sandbox-setup) - In the Fractal Sandbox environment, you will define the settings and workflows utilized in the platform features of Fractal for your integration.
   * Merchant Boarding
   * Payment Acceptance
   * Fees and Billing
   * Funding
3. [Testing and Migration](#testing-and-migration) - Once your sandbox application is set up, Fractal will help to test and migrate your implementation to the Fractal Production environment.
4. [Merchant Support Features](#merchant-support-features) - Enabling Fractal Merchant Support features gives your merchants the ability to manage disputes and run reports.

The diagram below illustrates how the Payments Integration and Support features work together to provide the benefits of the Fractal platform:

![Fractal Payment Workflow](https://uploads-ssl.webflow.com/663a214d683281c78ab2ac7c/666c5c4c3eb4d5128f01b838_TinyPNG%20illustration.png)

***

# Scope Of Work Creation

This resource outlines the Scope of Work requirements pre-Implementation.

All integrating Partners and software platforms work with the Fractal Solution Engineers and Sales Team to create a Scope of Work that describes what your integration will look like and the associated requirements across the Fractal Platform.

During Pre-Implementation, you will work with a Fractal Solution Engineer to fill in the Integration form. This page includes details about all of the information that you we will add to the form.

## Table of Contents

* 1. [Overview](#overview)
* 2. [Merchant Onboarding Details](#merchant-onboarding-details)
* 3. [Payment Workflow](#payment-workflow)
* 4. [Risk and Compliance](#risk-and-compliance)
* 5. [Funding/Disbursement](#funding-disbursement-integration)
* 6. [Partner Launch Timeline](#partner-pf-launch-timeline)

## Overview

Building a Scope of Work with our Prospect Platforms involves a discussion about Features and Risk Considerations and collects data on how our Clients hope to leverage the Fractal Platform across the 4 Merchant Support features related to Payment Facilitation:

* Merchant Boarding
* Payment Acceptance
* Fees, Billing, and Funding - tbd
* Merchant Support - tbd

## Merchant Onboarding Details

### Boarding Integration

Select your Merchant Boarding Integration. See the onboarding Integration Options table for an explanation of each option.

| Boarding Integration Options                                                                                                                                                                                                                                                                                                                                            | Note                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Portal - TBD                                                                                                                                                                                                                                                                                                                                                            | Clients will be boarded via the Fractal portal.                                                                                                                                                              |
| [Signup Form](https://staging-hosted.fractalpay.com/merchant-onboarding/02b3232aed11c23c7a8cbc164c48b51cbc09d7640ef84774467fb06d23e580eb6c4cfbc48c8715dab5e3d2be1310a201047caa60d3a72f61270cd374eb6ff2fa4f3c39433c08d3bbe94a44f78f83b4f09629b1751aeee1ba6ade0b7229a1d321aa3688798aa52c51b9953a1dba4cca5d614af674d5cf792679b4c464ca6fbc7c123495de989326e0d11856b952cf86) | Merchants will be boarded via an online signup form.                                                                                                                                                         |
| [Full API Boarding](/api-reference/merchant-onboarding/full-merchant-submit)                                                                                                                                                                                                                                                                                            | The Full Boarding API is a managed service allowing you complete flexibility in the creation of new merchant locations.                                                                                      |
| Bulk                                                                                                                                                                                                                                                                                                                                                                    | Fractal will work with you to meet the necessary technical and underwriting requirements for bulk onboarding, simplifying the process of migrating your existing Merchants to Fractal from another platform. |
| [Onboarding Webhooks](https://docs.fractalpay.com/Webhooks#merchant-onboarding)                                                                                                                                                                                                                                                                                         | The onboarding webhooks provide you complete awareness around the merchant onboarding process.                                                                                                               |

## Payment Workflow

| Question                                     | Note                                                                                                                                                                                                                                                                                    | Payment Methods                                                                                                                                                                             |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Please describe your ideal payment workflow: | **Example:** - Customer visits your website, selects products, clicks "pay now".  - The customer enters payment information to pay for the product. - Payment is approved, and the customer is given the option to save card details for future payments.  - The product is dispatched. | - Tokenization & Recurring Payments - Direct Portal Payments & Quick Charge  - Bridge Payments Custom Portal  - Direct API Payments  - Card Present Payments  - eCommerce & Online Payments |

| Payment Integration Options                                                         | Note                                                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [Widgets](https://ui.fractalpay.com/PayWidget)                                      | A suite of link and payment widgets that can be seamlessly embedded into your application.                               |
| [Links](https://docs.fractalpay.com/api-reference/endpoint/Create%20iFrame)         | An iframe solution where the payment capture process will occur either within the iFrame or on a hosted page.            |
| [Fractal JS](https://docs.fractalpay.com/EmbeddedPayments#faqs-and-troubleshooting) | An embeddable JavaScript tokenizer that encrypts card data, ensuring PCI compliance for your application.                |
| [Wallet](/api-reference/customers/request-card)                                     | Provides merchants with a collection of card-on-file and billing-on-file solutions via API.                              |
| [Charges Webhooks](https://docs.fractalpay.com/Webhooks#payment-success)            | A feature that allows the platform to receive real-time notifications when charges are captured on our hosted solutions. |

## Risk and Compliance

### Disputes and Chargebacks

| Question                                       | Note                                           |
| ---------------------------------------------- | ---------------------------------------------- |
| Portal Only                                    | Disputes are managed via the portal            |
| API Integration chargeback documents/responses | Disputes are managed by Partner/Client via API |

## Funding

| Question         | Note                                 |
| ---------------- | ------------------------------------ |
| Fractal Only     | Funding is managed via Fractal only. |
| Next-Day Funding | Funding is available the next day.   |

## Partner Launch Timeline

### Projected Timeline

| Question                                    | Description                                 |
| ------------------------------------------- | ------------------------------------------- |
| Implementation Kick-Off Call:               | Date of the first implementation call       |
| Anticipated Integration Target Start Date:  | When do you expect to start the integration |
| Anticipated Integration Target Finish Date: | Expected date to finalize integration       |
| Target Beta Onboarded:                      | Estimated Target Beta Onboarded Date        |
| Target Full Launch:                         | Target full launch date                     |


# Introduction
Source: https://docs.fractalpay.com/introduction

Welcome to the Fractal documentation

<img alt="Hero Light" />

<img alt="Hero Dark" />

## Welcome

Welcome to the documentation for our suite of Gateway APIs. This set of tools is designed to empower developers and SaaS platforms by providing a seamless and efficient interface to manage all things payments. From the onboarding of companies to the streamlined handling of payments, this suite of APIs is purpose-built to be robust, secure, and easy to integrate.