### Open Bank Link SDK with HTML Button

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

Provides the HTML code to create a button that, when clicked, opens the GrailPay Bank Link SDK. This is a user-initiated method to start the bank linking process.

```html
<button id="grp__pay">Link Bank Account</button>
```

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

### Transaction Capture Started Event

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered when an ACH debit has been successfully initiated for a transaction, indicating the start of the fund capture process from the payor's bank account.

```APIDOC
## Transaction Capture Started Event

### Description
This webhook is triggered when an ACH debit has been successfully initiated as part of a transaction. It indicates that the funds capture process has begun from the payor’s bank account.

### Method
POST

### Endpoint
Your configured webhook URL

### Request Body
- **event** (string) - The name of the event, "TransactionCaptureStarted".
- **uuid** (string) - Unique identifier for the transaction.
- **payer_uuid** (string) - Unique identifier for the payer.
- **payee_uuid** (string) - Unique identifier for the payee.
- **status** (string) - Current status of the transaction, e.g., "CAPTURE_ACH_PENDING".
- **capture_status** (string) - Status of the capture process.
- **payout_status** (null) - Placeholder for payout status.
- **clawback_status** (null) - Placeholder for clawback status.
- **reverse_payout_status** (null) - Placeholder for reverse payout status.
- **currency** (string) - Currency of the transaction (e.g., "USD").
- **amount** (integer) - Transaction amount in the smallest currency unit.
- **transaction_fee** (integer) - Transaction fee in the smallest currency unit.
- **client_reference_id** (string) - Optional client-provided reference ID.
- **payout_delay_days** (integer) - Number of days for payout delay.
- **type** (string) - Type of transaction initiation (e.g., "api").
- **created_at** (string) - Timestamp when the transaction was created.
- **updated_at** (string) - Timestamp when the transaction was last updated.

### Response Example
```json
{
    "event": "TransactionCaptureStarted",
    "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "status": "CAPTURE_ACH_PENDING",
    "capture_status": "CAPTURE_ACH_PENDING",
    "payout_status": null,
    "clawback_status": null,
    "reverse_payout_status": null,
    "currency": "USD",
    "amount": 12000,
    "transaction_fee": 300,
    "client_reference_id": "",
    "payout_delay_days": 2,
    "type": "api",
    "created_at": "2023-04-11 14:25:26",
    "updated_at": "2023-04-11 18:25:26"
}
```
```

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

### Refund Capture Started Event

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered each time a refund request has been initiated and a debit ACH has been created.

```APIDOC
## POST /webhooks/refund_capture_started

### Description
This webhook is triggered each time a refund request has been initiated and a debit ACH has been created from either the payee’s or processor’s bank account.

### Method
POST

### Endpoint
`/webhooks/refund_capture_started`

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, 'RefundCaptureStarted'.
- **uuid** (string) - Required - Unique identifier for the refund event.
- **transaction_uuid** (string) - Required - The UUID of the original transaction.
- **amount** (integer) - Required - The amount of the refund.
- **capture_delay_days** (integer) - Required - The number of days for capture delay.
- **payout_delay_days** (integer) - Required - The number of days for payout delay.
- **status** (string) - Required - The status of the refund, 'REFUND_CAPTURE_ACH_PENDING'.
- **payer_uuid** (string) - Required - The UUID of the payer.
- **payee_uuid** (string) - Required - The UUID of the payee.
- **client_reference_id** (string) - Optional - A client-defined reference ID.
- **created_at** (string) - Required - Timestamp when the event was created.
- **updated_at** (string) - Required - Timestamp when the event was last updated.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```
```

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

### Idempotency Key Usage Example

Source: https://docs.grailpay.com/docs/technical/idempotency

This example demonstrates how to include the `Idempotency-Key` header in a POST request to the `/3p/api/v1/register/person` endpoint. This ensures that the request can be safely retried if network issues occur.

```APIDOC
## POST /3p/api/v1/register/person (Idempotent Request)

### Description
This endpoint registers a person and supports idempotency to prevent duplicate entries. Include an `Idempotency-Key` header for safe retries.

### Method
POST

### Endpoint
/3p/api/v1/register/person

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **first_name** (string) - Required - The first name of the person.
- **last_name** (string) - Required - The last name of the person.
- **address** (object) - Required - The address details of the person.
  - **line_1** (string) - Required - The street address.
  - **city** (string) - Required - The city.
  - **state** (string) - Required - The state.
  - **zip** (string) - Required - The zip code.

### Request Example
```json
{
    "first_name": "Will",
    "last_name": "Clance",
    "address": {
        "line_1": "681 Avenue C",
        "city": "Bayonne",
        "state": "NJ",
        "zip": "07002"
    }
}
```

### Headers
- **Idempotency-Key** (string) - Required - A unique value generated by the client (e.g., V4 UUID) to ensure request idempotency. Max length 255 characters.
- **Accept** (string) - Optional - `application/json`
- **Content-Type** (string) - Required - `application/json`
- **Authorization** (string) - Required - Authentication token.

### Response
#### Success Response (200 or 201)
- **status** (string) - The status of the operation.
- **data** (object) - The registered person's details.

#### Response Example
```json
{
    "status": "success",
    "data": {
        "person_id": "pers_123abc",
        "first_name": "Will",
        "last_name": "Clance",
        "created_at": "2023-10-27T10:00:00Z"
    }
}
```

**Note**: Subsequent identical requests with the same `Idempotency-Key` within 24 hours will return the same response. After 24 hours, the key is purged, and a new request will be processed.
```

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

### Reverse Payout Started Event

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered when a reverse payout has been successfully initiated and is in the process of being completed.

```APIDOC
## Reverse Payout Started Event

### Description
This webhook is triggered when a reverse payout has been successfully initiated and is in the process of being completed.

### Method
POST

### Endpoint
`/websites/grailpay/webhooks`

### Parameters
#### Request Body
- **event** (string) - Required - The type of event, 'ReversePayoutStarted'.
- **uuid** (string) - Required - Unique identifier for the event.
- **payer_uuid** (string) - Required - Identifier for the payer.
- **payee_uuid** (string) - Required - Identifier for the payee.
- **status** (string) - Required - The current status of the payout.
- **capture_status** (string) - Required - The status of the capture.
- **payout_status** (string) - Required - The status of the payout.
- **clawback_status** (string) - Optional - The status of the clawback.
- **reverse_payout_status** (string) - Required - The status of the reverse payout.
- **currency** (string) - Required - The currency of the transaction.
- **amount** (integer) - Required - The amount of the transaction.
- **transaction_fee** (integer) - Required - The transaction fee.
- **client_reference_id** (string) - Optional - Client-defined reference ID.
- **payout_delay_days** (integer) - Optional - Number of days for payout delay.
- **type** (string) - Required - The type of transaction.
- **created_at** (string) - Required - Timestamp of event creation.
- **updated_at** (string) - Required - Timestamp of last update.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Webhook received successfully"
}
```

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

### ClawbackCaptureStarted Event

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered when a payout return (clawback) capture has been initiated by GrailPay as part of a refund or recovery process. It signifies the start of an attempt to recover disbursed funds.

```APIDOC
## POST /webhooks/clawback/started

### Description
This webhook is triggered when a payout return (clawback) capture has been initiated by GrailPay.

### Method
POST

### Endpoint
/webhooks/clawback/started

### Parameters
#### Query Parameters
None

#### Request Body
- **event** (string) - Required - The name of the event, "ClawbackCaptureStarted".
- **uuid** (string) - Required - Unique identifier for the clawback event.
- **payer_uuid** (string) - Required - Identifier for the payer.
- **payee_uuid** (string) - Required - Identifier for the payee.
- **status** (string) - Required - Current status of the clawback process.
- **capture_status** (string) - Required - Status of the fund capture attempt.
- **payout_status** (string) - Required - Status of the original payout.
- **clawback_status** (string) - Required - Specific status of the clawback.
- **reverse_payout_status** (string/null) - Optional - Status of any reversed payout.
- **currency** (string) - Required - The currency of the transaction (e.g., "USD").
- **amount** (integer) - Required - The amount of money being clawed back (in cents).
- **transaction_fee** (integer) - Required - The fee associated with the transaction (in cents).
- **client_reference_id** (string) - Optional - A reference ID provided by the client.
- **payout_delay_days** (integer) - Optional - The number of days the payout was delayed.
- **type** (string) - Required - The type of the transaction (e.g., "api").
- **failure_reason** (string) - Optional - Reason for any previous failure.
- **failure_code** (string) - Optional - Code associated with the failure reason.
- **created_at** (string) - Required - Timestamp when the event was created.
- **updated_at** (string) - Required - Timestamp when the event was last updated.

### Request Example
```json
{
    "event": "ClawbackCaptureStarted",
    "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "status": "CLAWBACK_ACH_PENDING",
    "capture_status": "CAPTURE_ACH_FAILED",
    "payout_status": "PAYOUT_COMPLETE",
    "clawback_status": "CLAWBACK_ACH_PENDING",
    "reverse_payout_status": null,
    "currency": "USD",
    "amount": 12000,
    "transaction_fee": 300,
    "client_reference_id": "",
    "payout_delay_days": 2,
    "type": "api",
    "failure_reason": "Insufficient funds",
    "failure_code": "R01",
    "created_at": "2023-04-11 14:25:26",
    "updated_at": "2023-04-11 18:25:26"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```
```

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

### Include Production SDK Script in HTML

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

This code snippet demonstrates how to include the Bank Link SDK script for the production environment in your HTML file. Use this for live operations.

```javascript
<script type="text/javascript" src="https://bank-link-widget.grailpay.com/sdk.js"></script>
```

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

### Handle User Creation Event (TypeScript)

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

Defines the structure for user creation data and a callback function to handle this event. This is used to process information when a new user is created within the system.

```typescript
interface UserCreatedObject {
    userId: string;
    role: string;
    created_at: string;
  }

  const onUserCreated = (data: UserCreatedObject) => {
    // Your action
  }
```

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

### Clawback Started Event

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered when a payout return (clawback) has been initiated by the GrailPay system, but the ACH debit has not been created. A clawback is required when a transaction fails after the payout has been disbursed.

```APIDOC
## POST /webhooks/clawback-started

### Description
This webhook is triggered when a payout return (clawback) has been initiated by the GrailPay system, but the ACH debit has not been created.

### Method
POST

### Endpoint
/webhooks/clawback-started

### Request Body
- **event** (string) - Required - The name of the event, "ClawbackStarted".
- **uuid** (string) - Required - Unique identifier for the event.
- **payer_uuid** (string) - Required - The UUID of the payer.
- **payee_uuid** (string) - Required - The UUID of the payee.
- **status** (string) - Required - The overall status of the clawback, e.g., "CLAWBACK_PENDING".
- **capture_status** (string) - Required - The status of the ACH debit capture, e.g., "CAPTURE_ACH_FAILED".
- **payout_status** (string) - Required - The status of the payout, e.g., "PAYOUT_COMPLETE".
- **clawback_status** (string) - Required - The specific status of the clawback process.
- **reverse_payout_status** (string or null) - Optional - The status of the reverse payout, if applicable.
- **currency** (string) - Required - The currency of the transaction (e.g., "USD").
- **amount** (integer) - Required - The amount involved in the clawback in the smallest currency unit (e.g., cents).
- **transaction_fee** (integer) - Required - The transaction fee in the smallest currency unit.
- **client_reference_id** (string) - Optional - A custom reference ID provided by the client.
- **payout_delay_days** (integer) - Optional - The number of days the payout was delayed.
- **type** (string) - Required - The type of transaction, e.g., "api".
- **failure_reason** (string or null) - Optional - The reason for the failure, if any.
- **failure_code** (string or null) - Optional - The code associated with the failure, if any.
- **created_at** (string) - Required - The timestamp when the event was created (YYYY-MM-DD HH:MM:SS).
- **updated_at** (string) - Required - The timestamp when the event was last updated (YYYY-MM-DD HH:MM:SS).

### Request Example
{
  "event": "ClawbackStarted",
  "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
  "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
  "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
  "status": "CLAWBACK_PENDING",
  "capture_status": "CAPTURE_ACH_FAILED",
  "payout_status": "PAYOUT_COMPLETE",
  "clawback_status": "CLAWBACK_PENDING",
  "reverse_payout_status": null,
  "currency": "USD",
  "amount": 12000,
  "transaction_fee": 300,
  "client_reference_id": "",
  "payout_delay_days": 2,
  "type": "api",
  "failure_reason": null,
  "failure_code": null,
  "created_at": "2023-04-11 14:25:26",
  "updated_at": "2023-04-11 18:25:26"
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Webhook received successfully"
}
```

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

### Transaction Started Event Webhook

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This webhook is triggered when a transaction has been successfully created in the GrailPay system but ACH processing has not yet begun. It marks the initial step in the transaction lifecycle.

```APIDOC
## POST /webhooks/transaction-started

### Description
This endpoint receives the 'Transaction Started' webhook event from GrailPay. This event signifies that a transaction has been successfully created in the GrailPay system, but the ACH processing has not yet commenced.

### Method
POST

### Endpoint
/webhooks/transaction-started

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, which is 'TransactionStarted'.
- **uuid** (string) - Required - The unique identifier for the transaction.
- **payer_uuid** (string) - Required - The unique identifier for the payer.
- **payee_uuid** (string) - Required - The unique identifier for the payee.
- **status** (string) - Required - The overall status of the transaction (e.g., 'CAPTURE_PENDING').
- **capture_status** (string) - Required - The status related to capturing the transaction funds.
- **payout_status** (string) - Optional - The status of the payout, can be null.
- **clawback_status** (string) - Optional - The status of any clawback, can be null.
- **reverse_payout_status** (string) - Optional - The status of any reversed payout, can be null.
- **currency** (string) - Required - The currency of the transaction (e.g., 'USD').
- **amount** (integer) - Required - The transaction amount in the smallest currency unit (e.g., cents for USD).
- **transaction_fee** (integer) - Required - The transaction fee in the smallest currency unit.
- **client_reference_id** (string) - Optional - A reference ID provided by the client.
- **payout_delay_days** (integer) - Required - The number of days until the payout is delayed.
- **type** (string) - Required - The type of transaction, usually 'api'.
- **created_at** (string) - Required - The timestamp when the transaction was created (YYYY-MM-DD HH:MM:SS).
- **updated_at** (string) - Required - The timestamp when the transaction was last updated (YYYY-MM-DD HH:MM:SS).

### Request Example
```json
{
    "event": "TransactionStarted",
    "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "status": "CAPTURE_PENDING",
    "capture_status": "CAPTURE_PENDING",
    "payout_status": null,
    "clawback_status": null,
    "reverse_payout_status": null,
    "currency": "USD",
    "amount": 12000,
    "transaction_fee": 300,
    "client_reference_id": "",
    "payout_delay_days": 2,
    "type": "api",
    "created_at": "2023-04-11 14:25:26",
    "updated_at": "2023-04-11 18:25:26"
}
```

### Response
#### Success Response (200)
An empty response with a 200 OK status code is expected upon successful receipt of the webhook.

#### Response Example
(No specific JSON body is returned for success, only a 200 status code.)
```

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

### Include Sandbox SDK Script in HTML

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

This code snippet shows how to include the Bank Link SDK script for the sandbox environment directly in your HTML file. It is used for development and testing purposes.

```javascript
<script type="text/javascript" src="https://bank-link-widget-sandbox.grailpay.com/sdk.js"></script>
```

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

### Onboarding with Manual Account Entry and Account Intelligence

Source: https://docs.grailpay.com/docs/technical/users/onboard-a-merchant

This endpoint allows for manual onboarding of a person by providing their account details. It also supports real-time bank account validation via the Account Intelligence product to reduce fraud risk and ensure fund routing accuracy.

```APIDOC
## POST /websites/grailpay

### Description
Manually onboard a person by providing their account details. Real-time bank account validation using Account Intelligence is recommended to reduce fraud risk and ensure funds can be successfully routed.

### Method
POST

### Endpoint
/websites/grailpay

### Parameters
#### Request Body
- **account_number** (string) - Required - The account number for the user.
- **routing_number** (string) - Required - The routing number for the user's bank.
- **account_name** (string) - Required - The name of the account holder.
- **account_type** (string) - Required - The type of account, either `checking` or `savings`.
- **actions** (object) - Optional - An object to enable real-time validation features.
  - **account_intelligence** (object) - Optional - Configuration for Account Intelligence validation.
    - **version** (string) - Required - The version of Account Intelligence to use (e.g., "v3").
    - **name_match** (boolean) - Optional - Whether to enable name matching against the account holder's name.

### Request Example
```json
{
  "account_number": "123456789",
  "routing_number": "012345678",
  "account_name": "John Doe",
  "account_type": "checking",
  "actions": {
    "account_intelligence": {
      "version": "v3",
      "name_match": true
    }
  }
}
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the onboarded merchant, required for future operations.
- **name** (string) - Echoed value of the user's name.
- **address** (object) - Echoed value of the user's address.
- **onboarding_status** (string) - The current status of the onboarding process.
- **kyb_status** (string) - The Know Your Business (KYB) status of the merchant.
- **account_intelligence_result** (object) - An object containing the results of the Account Intelligence validation (if requested).

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "John Doe",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "12345"
  },
  "onboarding_status": "completed",
  "kyb_status": "approved",
  "account_intelligence_result": {
    "validation_status": "passed",
    "risk_score": 0.15,
    "decisioning_insights": [
      "account_format_valid",
      "name_match_successful"
    ]
  }
}
```
```

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

### Initialize Bank Link SDK with TypeScript Types

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

Demonstrates the initialization of the Bank Link SDK using TypeScript, defining interfaces for initialization properties (InitProps) and response types (InitSuccess, InitFail, Response). It includes optional parameters for theme customization and callback functions for various events.

```typescript
interface InitSuccess {
    status: 200;
  }

  interface InitFail {
    status: number;
    message: string;
  }

  interface Response {
  	status: boolean;
    code: number;
  }

  interface InitProps {
    token: string;
    userId?: string;
    vendorId?: string;
    role?: string;
    timeout?: number;
    theme?: {
      branding_name?: string;
      screens?: {
      	finder?: {
         	 subtitle?: string;
           searchPlaceholder?: string;
        }
      }
    },
    onError?: (data: ErrorData) => void;
    onUserCreated?: (data: UserData) => void;
    onBankConnected?: (data: any) => void;
  }

  type init = (props: InitProps) => Promise<InitSuccess | InitFail>

  window.grailpay.init({
    token: 'GRAILPAY_ACCESS_TOKEN',
    userId: 'USER_UUID',
    vendorId: 'VENDOR_ID',
    role: 'USER_ROLE',
    timeout: 'CALLBACK_TIMEOUT',
    onError: function (error) {
      console.error('Error happened', error);
    },
    onUserCreated: function (data) {
      console.log('User created', data);
    },
    onBankConnected: function (data) {
      console.log('Bank detail', data);
    },
  })
  .then((res:Response) => {
  	console.log('Response', res);
  });
```

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

### GET /3p/api/v2/merchants/{merchant_id}/billing

Source: https://docs.grailpay.com/docs/technical/billing/get-merchant-billing-summary

Retrieves a summary of billing events for a specific merchant. Supports filtering by a date range.

```APIDOC
## GET /3p/api/v2/merchants/{merchant_id}/billing

### Description
Retrieves a summary of billing events for a specific merchant, detailing occurrences and costs for each billable event. This endpoint can be filtered by a date range.

### Method
GET

### Endpoint
`/3p/api/v2/merchants/{merchant_id}/billing`

### Parameters
#### Path Parameters
- **merchant_id** (string) - Required - The unique identifier for the merchant.

#### Query Parameters
- **start_date** (string) - Optional - The start date for filtering billing events (YYYY-MM-DD).
- **end_date** (string) - Optional - The end date for filtering billing events (YYYY-MM-DD).

### Request Example
```json
{
  "example": "GET /3p/api/v2/merchants/abcd-efgh-ijkl-mnop/billing?start_date=2025-01-01&end_date=2025-01-31"
}
```

### Response
#### Success Response (200)
- **summary** (array) - An array of billing event summaries.
  - **billable_event** (string) - The type of billing event (e.g., "Standard ACH").
  - **total_occurrences** (integer) - The total number of times this event occurred.
  - **amount_per_occurrence** (integer) - The cost of a single occurrence in cents.
  - **total** (integer) - The total cost for this event type in cents.

#### Response Example
```json
{
  "example": {
    "summary": [
      {
        "billable_event": "Standard ACH",
        "total_occurrences": 10,
        "amount_per_occurrence": 10,
        "total": 100
      }
    ]
  }
}
```
```

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

### Initialize Bank Link SDK in JavaScript

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

Initializes the Bank Link SDK with provided properties including token, user ID, vendor ID, role, timeout, theme, and callback functions for error handling, user creation, bank connection, link exit, and default account linking. The method returns a promise that resolves with a response object.

```javascript
window.grailpay.init({
    token: 'GRAILPAY_ACCESS_TOKEN',
    userId: 'USER_UUID',
    vendorId: 'VENDOR_ID',
    role: 'USER_ROLE',
    timeout: 'CALLBACK_TIMEOUT',
    theme: {
      branding_name: 'COMPANY_NAME',
      screens: {
       	finder: {
        	subtitle: 'FINDER_SCREEN_SUBTITLE',
          searchPlaceholder: 'SEARCH_INPUT_PLACEHOLDER_TEXT',
        }
      }
    },
    onError: function (error) {
      console.error('Error happened', error);
    },
    onUserCreated: function (data) {
      console.log('User created', data);
    },
    onBankConnected: function (data) {
      console.log('Bank detail', data);
    },
    onLinkExit: function(data) {
      console.log('Data', data);
    },
    onLinkedDefaultAccount: function(data) {
    	console.log('Default Account', data);
  	},
  })
  .then(res => {
    console.log('Response', res);
  });
```

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

### Refund Capture Started Event Payload (JSON)

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This JSON payload is sent when a refund request is initiated and a debit ACH has been created. It signifies the start of the refund capture process and includes details relevant to the initiation.

```json
{
    "event": "RefundCaptureStarted",
    "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
    "transaction_uuid": "7049f46f-8502-402e-952b-b29ad5ec8a55",
    "amount": 12000,
    "capture_delay_days": 1,
    "payout_delay_days": 2,
    "status": "REFUND_CAPTURE_ACH_PENDING",
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "client_reference_id": "",
    "created_at": "2023-04-11 14:25:26",
    "updated_at": "2023-04-11 18:25:26"
}
```

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

### Webhook Overview and Authentication

Source: https://docs.grailpay.com/docs/technical/webhooks/events

Information on how webhooks work, security measures, and how to authenticate incoming webhook requests.

```APIDOC
## Webhook Events Overview

Webhooks allow your application to react in real-time to important events across the GrailPay platform. GrailPay sends a secure HTTP POST request directly to your server with event details when a subscribed event occurs. This enables automation of workflows, data synchronization, and triggering time-sensitive actions.

### Authenticating Webhooks

To verify the authenticity of webhook requests, GrailPay includes a `X-Caller-Auth` header containing a `SHA-256` hash of your API key. This header should be validated in your server-side code to ensure requests originate from GrailPay.

### Security

All webhook endpoints must use HTTPS to guarantee secure delivery of sensitive financial event data in both sandbox and production environments. Non-secure HTTP URLs will be rejected.

### Response & Retry Logic

Your server must respond with an HTTP `200 OK` status code to acknowledge receipt of a webhook event. If a `200 OK` is not returned, GrailPay will retry delivery at increasing intervals. Your webhook handler should be idempotent and efficient, responding quickly to ensure reliable communication.
```

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

### Sandbox Testing Environment

Source: https://docs.grailpay.com/docs/technical/overview

Information on how to connect to and utilize the GrailPay sandbox environment for testing API integrations, including details on test bank accounts and SSNs.

```APIDOC
## Sandbox API Environment

### Description
This guide details how to test your integration within GrailPay’s sandbox environment. It includes instructions for simulating bank accounts and adhering to specific formatting rules for Social Security Numbers (SSNs).

### Sandbox API Endpoint
`https://api-sandbox.grailpay.com`

### Testing Bank Accounts
To simulate bank accounts in the sandbox:
* Use a random 12-digit account number.
* Use one of the following test routing numbers:
  * `226078036`
  * `221979363`

### Testing Social Security Numbers (SSNs)
SSNs used for testing must adhere to the following rules:
* **Cannot** begin with `"000"` or any value in the range `"900–999"`.
* **Cannot** have `"00"` as the middle two digits.
* **Cannot** end in `"0000"`.

Any other valid 9-digit SSN format outside these constraints is acceptable.
```

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

### Retrieve All Billing Events for a Merchant

Source: https://docs.grailpay.com/docs/technical/billing/get-merchant-billing-summary

This code snippet demonstrates how to make a GET request to retrieve all billing events for a specific merchant. It requires the merchant's UUID as a path parameter.

```HTTP
GET /3p/api/v2/merchants/abcd-efgh-ijkl-mnop/billing
```

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

### Programmatically Open Bank Link SDK (JavaScript)

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

Demonstrates how to open the GrailPay Bank Link SDK programmatically using JavaScript. This allows for triggering the SDK based on application events rather than direct user clicks on a dedicated button.

```javascript
// Example function to programmatically open the Bank Link SDK
function openGrailPayWidget() {
  window.grailpay.open();
}

// Call the function whenever you want to open the widget
// For example, when the user clicks on a different element or performs a certain action
document.getElementById("open-widget-button").addEventListener("click", openGrailPayWidget);
```

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

### Transaction Started Event Payload (JSON)

Source: https://docs.grailpay.com/docs/technical/webhooks/events

This JSON payload represents the data structure sent by GrailPay when a transaction has started but ACH processing has not yet commenced. It includes details such as event type, transaction identifiers, currency, amount, and timestamps. This payload is crucial for understanding the initial state of a transaction within the GrailPay system.

```json
{
    "event": "TransactionStarted",
    "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "status": "CAPTURE_PENDING",
    "capture_status": "CAPTURE_PENDING",
    "payout_status": null,
    "clawback_status": null,
    "reverse_payout_status": null,
    "currency": "USD",
    "amount": 12000,
    "transaction_fee": 300,
    "client_reference_id": "",
    "payout_delay_days": 2,
    "type": "api",
    "created_at": "2023-04-11 14:25:26",
    "updated_at": "2023-04-11 18:25:26"
}
```

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

### Dynamically Load SDK Script Asynchronously

Source: https://docs.grailpay.com/docs/technical/bank-link-sdk/overview

This JavaScript code snippet shows an alternative method to load the Bank Link SDK script asynchronously after the page has rendered. It dynamically creates a script element and appends it to the document's head, allowing for better control over the loading process using the 'onload' event.

```javascript
const GRAILPAY_SCRIPT = 'https://gp-bank-link-widget-grailpay.com/sdk.js';
const script = document.createElement('script');
script.setAttribute('src', GRAILPAY_SCRIPT);
document.head.appendChild(script);
```

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

### GET /3p/api/v2/transactions/{transaction_uuid}

Source: https://docs.grailpay.com/docs/technical/transactions/create-a-transaction

Use this endpoint to fetch the current status of a specific transaction by providing its unique identifier.

```APIDOC
## GET /3p/api/v2/transactions/{transaction_uuid}

### Description
Fetches the current status of a specific transaction.

### Method
GET

### Endpoint
`/3p/api/v2/transactions/{transaction_uuid}`

### Parameters
#### Path Parameters
- **transaction_uuid** (string) - Required - The unique identifier of the transaction.

#### Query Parameters
(None specified in the source text)

#### Request Body
(None specified for GET request)

### Request Example
(No specific request example provided for this endpoint in the source text)

### Response
#### Success Response (200)
- **status** (string) - The current status of the transaction (e.g., `CAPTURE_PENDING`, `IN_PAYOUT`).

#### Response Example
```json
{
  "transaction_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "CAPTURE_PENDING"
}
```
```

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

### Access Token Creation

Source: https://docs.grailpay.com/docs/risk/authentication

Clients authenticate by sending a POST request to the /v1/auth endpoint with their client_id and client_secret to obtain an access token and a refresh token.

```APIDOC
## POST /v1/auth

### Description
Authenticates a client using `client_id` and `client_secret` to obtain JWT-based tokens.

### Method
POST

### Endpoint
/v1/auth

### Parameters
#### Request Body
- **client_id** (string) - Required - The client identifier provided by customer support.
- **client_secret** (string) - Required - The client secret provided by customer support.

### Request Example
```json
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - A short-lived token used for authenticating subsequent API requests.
- **refresh_token** (string) - A token used to renew the access token without re-authenticating.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def456ghi789jkl0mno..."
}
```
```

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

### GET /v3/webhooks/events

Source: https://docs.grailpay.com/docs/technical/webhooks/manage-webhooks

Retrieve a list of all supported webhook event types. This endpoint provides a dynamic list of events that can trigger webhook notifications.

```APIDOC
## GET /v3/webhooks/events

### Description
Retrieve a list of all supported webhook event types. This endpoint provides a dynamic list of events that can trigger webhook notifications.

### Method
GET

### Endpoint
/v3/webhooks/events

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **events** (array) - A list of strings, where each string is a supported webhook event name.

#### Response Example
{
  "events": [
    "transaction.created",
    "transaction.succeeded",
    "payout.failed"
  ]
}
```

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

### List All Batch Refunds

Source: https://docs.grailpay.com/docs/technical/refunds/manage-refunds

Fetch a list of all batch refunds with support for filtering by status, date range, and pagination. Results can be sorted to prioritize recent activity.

```APIDOC
## GET /v1/refunds/batches

### Description
Retrieves a list of all batch refunds, with options for filtering, sorting, and pagination.

### Method
GET

### Endpoint
/v1/refunds/batches

#### Query Parameters
- **status** (string) - Optional - Filters refunds by their status (e.g., 'processed', 'failed').
- **startDate** (string) - Optional - Filters refunds created on or after this date (YYYY-MM-DD).
- **endDate** (string) - Optional - Filters refunds created on or before this date (YYYY-MM-DD).
- **limit** (integer) - Optional - The maximum number of results to return per page (default: 20).
- **offset** (integer) - Optional - The number of results to skip before starting to collect the result set.
- **sortBy** (string) - Optional - Field to sort by (e.g., 'createdAt', 'amount').
- **sortOrder** (string) - Optional - Sorting order ('asc' or 'desc', default: 'desc').

### Response
#### Success Response (200)
- **data** (array) - A list of batch refund objects.
  - Each object contains:
    - **uuid** (string) - The unique identifier of the batch refund.
    - **amount** (integer) - The total refund amount for the batch.
    - **currency** (string) - The currency of the refund amount.
    - **status** (string) - The current status of the batch refund.
    - **createdAt** (string) - The timestamp when the batch refund was created.
- **totalCount** (integer) - The total number of batch refunds available matching the query.

#### Response Example
```json
{
  "data": [
    {
      "uuid": "b1a2b3c4-d5e6-f7a8-9b0c-1d2e3f4a5b6c",
      "amount": 15000,
      "currency": "USD",
      "status": "processed",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "uuid": "c2d3e4f5-a6b7-c8d9-e0f1-2a3b4c5d6e7f",
      "amount": 5000,
      "currency": "USD",
      "status": "failed",
      "createdAt": "2023-10-26T09:30:00Z"
    }
  ],
  "totalCount": 50
}
```
```