### Example Authorization Header

Source: https://docs.checkbook.io/docs/integrations/oauth

An example of how the Authorization header would look with a specific access token.

```http
Authorization: bearer Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z
```

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

### Prepared Payload Example for Signature Generation

Source: https://docs.checkbook.io/docs/api/webhooks

Example of the prepared payload for signature generation, which concatenates the webhook body and the nonce. Ensure exact spacing.

```text
{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }1243549809
```

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

### Webhook Signing Key Example

Source: https://docs.checkbook.io/docs/api/webhooks

Example of a Checkbook webhook signing key. This key is used to generate and verify webhook signatures.

```text
335b5728e25b582e88995fce207bff380
```

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

### Webhook Request Example

Source: https://docs.checkbook.io/docs/api/webhooks

Example of an incoming webhook POST request, including headers and payload. The signature header contains nonce and signature values.

```http
POST https://dundermifflin.com/webhook/checkbook
Content-Type: application/json
signature: nonce=1243549809,signature=ee23a8e152384caa501647cf550c9b7c3e74162af2811863d1c5f62f67b93bb2
 
{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }
```

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

### API Authorization Header Example

Source: https://docs.checkbook.io/docs/api/authentication

Include your publishable and secret keys, separated by a colon, in the Authorization header for HTTP requests.

```http
Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8
```

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

### Example cURL Request with Idempotency-Key

Source: https://docs.checkbook.io/docs/api/idempotent-requests

Include the `Idempotency-Key` header in your POST requests to ensure idempotency. This key should be a unique string for each operation.

```curl
curl -X POST \
  -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: employee-of-the-month-bonus-payment-id22" \
  -d '{
    "name": "Dwight Schrute",
    "recipient": "dwight@dundermifflin.com",
    "amount": 500.00,
    "description": "Employee of the Month Bonus"
  }' \
  https://demo.checkbook.io/v3/check/digital
```

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

### Invoice Webhook Example

Source: https://docs.checkbook.io/docs/api/webhooks

This JSON object details a webhook event for an invoice status update. It contains the invoice ID and its current status.

```json
{
  "status": "PAID",
  "id": "438fd2d78d7b4b579d6d0968633768f3",  
  "type": "INVOICE"
}
```

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

### Wallet Webhook Example

Source: https://docs.checkbook.io/docs/api/webhooks

This JSON object represents a webhook for incoming funds applied to a Checkbook wallet. It includes the wallet ID, transaction amount, and updated balance.

```json
{
  "amount": 500.00,
  "balance": 1852.23,
  "id": "5b7946d45a7a4c7eb457cb7fe05250b3",  
  "type": "PREFUND_ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28",
  "description": "Dinner party Dundie Award refund"
}
```

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

### Payment Webhook Example

Source: https://docs.checkbook.io/docs/api/webhooks

This JSON object represents a webhook notification triggered by a change in a payment's status. It includes the payment ID and its new status.

```json
{
  "status": "IN_PROCESS",
  "id": "8b0ececd521c425db52cddf8d6930d54",  
  "type": "CHECK",
  "deposit_option": "ACH"
}
```

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

### Example Error Response JSON

Source: https://docs.checkbook.io/docs/api/error-codes

This JSON structure is returned when an API request fails, providing specific details about the error and potentially the problematic parameter.

```json
{
  "error": "JSON body parameters are invalid.",
  "more_info": {
    "amount": "Must be greater than or equal to 0.01."
  }
}
```

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

### Bank Account Webhook Example

Source: https://docs.checkbook.io/docs/api/webhooks

This JSON payload signifies a webhook notification for a bank account status change, such as verification completion. It includes the account ID and associated user ID.

```json
{
  "status": "VERIFIED",
  "id": "1bc0ce5ce7cf447ca9f2dad1ee2a98ce",  
  "type": "ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28"
}
```

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

### Integrate Deposit Widget for Bank Accounts

Source: https://docs.checkbook.io/docs/products/widgets

Use the Deposit widget to collect banking information for payment deposits. It integrates seamlessly into your software for a smooth user experience.

```html
<html>
   <head>
      <script src="https://sandbox.checkbook.io/embed/checkbook-embed.js"></script>
   </head>
   <body>
      <script type="text/javascript">
         checkbook.deposit.Bank({token: 'eyJhbGciOiJIUzI1NiIsImtpZCI6IjMyMDEyMzA5Yzk5ZTEzYzI0ZjE2MjAwNzIzZmZlNDMzIiwidHlwIjoiSldUIn0.eyJpZCI6IjNmZmNjN2U1YWQzYjQ2ZDhhOTRmYjQ1MjBiZGI2OGY3In0.iDeR_eFSpNRQ_FsJQzVz0qokM1Qdevitd7Dy7Y3me-s',
         onSuccess: (res) => {
         },
         onError: (res) => {
         }}).render('#container');
      </script>
      <div id="container" style="width: 600px !important; height:700px !important;">
      </div>
   </body>
</html>
```

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

### User Status Change Webhook

Source: https://docs.checkbook.io/docs/api/webhooks

A webhook is generated when a user's status changes, for example from 'PENDING' to 'VERIFIED'. The payload contains the updated status, user ID, and event type.

```json
{
  "status": "VERIFIED",
  "id": "47eb74bc049d4990b53983bd976ec2e9",  
  "type": "USER"
}
```

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

### Onboard Bank Accounts with Add Account Widget

Source: https://docs.checkbook.io/docs/products/widgets

Use the Add Account widget to collect bank and card information directly within your application. This widget ensures a seamless user experience and leverages Checkbook's compliance solutions.

```html
<html>
   <head>
      <script src="https://sandbox.checkbook.io/embed/checkbook-embed.js"></script>
   </head>
   <body>
      <script type="text/javascript">
         checkbook.account.AddBank({token: 'eyJhbGciOiJIUzI1NiIsImtpZCI6IjhhZTQyNGJmMWNmNzczMWEwMTczNDRjMmE4NTNkODc0IiwidHlwIjoiSldUIn0.eyJpZCI6IjgwNmU1YjYwM2ExNTRhYWE5Njc1ZDU3YzIyNzg2NzgwIn0.ErsG_3FDvJMb5zGe-_mk1HPmjCUyH8FowDpGtENbE28',
         onSuccess: (res) => {
         },
         onError: (res) => {
         }}).render('#container');
      </script>
      <div id="container" style="width: 600px !important; height:700px !important;">
      </div>
   </body>
</html>
```

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

### Access Token Response

Source: https://docs.checkbook.io/docs/integrations/oauth

This JSON object is returned upon successful authentication, containing the access token and other relevant details.

```json
{
  "access_token": "Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z", 
  "token_type": "Bearer", 
  "expires_in": 15552000, 
  "refresh_token": "v0sRbFofMnKB2GmMyGnoOsot1VbpDU", 
  "scope": "check"
}
```

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

### Wallet Webhook

Source: https://docs.checkbook.io/docs/api/webhooks

This webhook is generated when incoming funds are successfully applied to a Checkbook wallet.

```APIDOC
## Wallet Webhook

### Description
This webhook is triggered when incoming funds are successfully applied to a Checkbook wallet. The `PREFUND_ACCOUNT` type is the best indicator that funds have been applied.

### Event Payload Example
```json
{
  "amount": 500.00,
  "balance": 1852.23,
  "id": "5b7946d45a7a4c7eb457cb7fe05250b3",
  "type": "PREFUND_ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28",
  "description": "Dinner party Dundie Award refund"
}
```

### Fields
Key| Description  
---|---
**amount** (number) - Required| Amount of the funds application.  
**balance** (number) - Required| New balance of the wallet, after the application of the funds.  
**id** (string) - Required| ID of the wallet.  
**type** (string) - Required| Type of webhook received. For this event, it will be `PREFUND_ACCOUNT`.  
**user_id** (string) - Required| ID of the user associated with the wallet.  
**description** (string) - Optional| Additional details associated with the payment.
```

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

### Authorization Request

Source: https://docs.checkbook.io/docs/integrations/oauth

Initiates the OAuth 2.0 flow by redirecting the user to Checkbook's authorization server. Requires client ID, redirect URI, response type, and scope.

```APIDOC
## Authorization Request

### Description
Redirects the user's browser to the Checkbook authorization server to request authorization for your application.

### Method
GET

### Endpoint
`https://app.checkbook.io/oauth/authorize`

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID obtained during application registration.
- **redirect_uri** (string) - Required - The URI where Checkbook will redirect the user after authorization.
- **response_type** (string) - Required - Must be set to `code` for the Authorization Code Grant.
- **scope** (string) - Required - Specifies the access level. Accepted values: `check` (multiple uses) or `single-use` (one use).
```

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

### Request Access Token with Authorization Code

Source: https://docs.checkbook.io/docs/integrations/oauth

This POST request exchanges the authorization code for an access token. Ensure all parameters, including client ID, secret, redirect URI, and scope, are correctly configured.

```http
POST https://app.checkbook.io/web/v1/auth/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=313910200b834c009f62ae47feeee407&grant_type=authorization_code&scope=check&code=8hXMj1T9D36qL2uzb19s5OaNnkT6Vq&redirect_uri=https://dundermifflin.com&client_secret=dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8
```

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

### HMAC Signature Verification

Source: https://docs.checkbook.io/docs/api/webhooks

This Java code demonstrates how to compute the HMAC-SHA256 signature for incoming webhook requests to verify their authenticity.

```APIDOC
## Compute HMAC Signature

This Java code snippet shows how to compute the HMAC-SHA256 signature for a given payload and secret key.

### Method
`computeSignature(String message, String secretKey)`

### Parameters
- **message** (String) - The data to sign, typically the payload concatenated with the nonce.
- **secretKey** (String) - Your webhook signing key.

### Returns
- **String** - The computed HMAC-SHA256 signature in hexadecimal format.

### Example Usage
```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class HmacVerifier {

    public static String computeSignature(String message, String secretKey) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        String hex = "";
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        for (byte i : hmacBytes) {
            hex += String.format("%02x", i);
        }
        return hex;
    }

    public static void main(String[] args) {
        String webhookKey = "YOUR_WEBHOOK_KEY"; // Replace with your actual webhook key
        String nonce = "SOME_NONCE"; // The nonce received in the header
        String payload = "{ \"id\": \"some_id\" }"; // The webhook payload

        String dataWithNonce = payload + nonce;

        try {
            String signature = computeSignature(dataWithNonce, webhookKey);
            System.out.println("Computed Signature: " + signature);
            // Compare this signature with the 'signature' header value
        } catch (Exception e) {
            System.err.println("Error computing signature: " + e.getMessage());
        }
    }
}
```

#### Compare the hash
Compare the generated hash with the `signature` value in the `signature` header. If they match, the request is authentic.
```

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

### Authorization Header Format

Source: https://docs.checkbook.io/docs/integrations/oauth

Use this format for the Authorization header when making requests to protected API endpoints.

```http
Authorization: bearer {access_token}
```

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

### Obtain Access Token

Source: https://docs.checkbook.io/docs/integrations/oauth

The Checkbook authorization server issues an access_token upon successful credential verification. This token is used for subsequent API requests.

```APIDOC
## Obtain Access Token

### Description
Upon successful verification of credentials, the Checkbook authorization server issues an `access_token` to the client application. This token, along with its type, expiration time, a `refresh_token`, and granted scopes, is returned in a JSON object.

### Response
#### Success Response (200)
- **access_token** (string) - The token used for authenticating API requests.
- **token_type** (string) - The type of token, typically 'Bearer'.
- **expires_in** (integer) - The time in seconds until the access token expires.
- **refresh_token** (string) - A token used to obtain a new access token without re-authorization.
- **scope** (string) - The scope of access granted by the token.

### Response Example
```json
{
  "access_token": "Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z", 
  "token_type": "Bearer", 
  "expires_in": 15552000, 
  "refresh_token": "v0sRbFofMnKB2GmMyGnoOsot1VbpDU", 
  "scope": "check"
}
```
```

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

### Resource Access with Access Token

Source: https://docs.checkbook.io/docs/integrations/oauth

Client applications use the obtained access_token in the Authorization header to make authenticated requests to the Checkbook API.

```APIDOC
## Resource Access

### Description
To access protected resources on the Checkbook API, the client application must include the `access_token` in the `Authorization` header of its HTTP requests. The header should be formatted as `Authorization: bearer {access_token}`.

### Request Example
```
Authorization: bearer Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z
```
```

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

### Standard CSV Template for Bulk Payments

Source: https://docs.checkbook.io/docs/products/payments/bulk

Use this CSV format for sending single-recipient payments in bulk. Ensure columns match exactly: Name, Address, Amount, Check Number (optional), and Description.

```csv
Name,Address,Amount,Check Number,Description
Dwight Schrute,dwight@dundermifflin.com,500.00,1001,Employee of the Month Bonus
Schrute Farms,"Rural Rt. 6, Honesdale PA 18431",750,1002,Monthly beet shipment
Kevin Malone,kevin@dundermifflin.com,15.99,1003,Chili delivery
```

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

### User Status Change Webhook

Source: https://docs.checkbook.io/docs/api/webhooks

A webhook is generated when a user's status changes, such as transitioning from 'PENDING' to 'VERIFIED'.

```APIDOC
## User Status Change Webhook

### Description
This webhook is triggered when a user's status is updated. The payload includes the new status, the ID of the user, and the type of webhook.

### Event
USER_STATUS_CHANGED

### Payload Structure
```json
{
  "status": "VERIFIED",
  "id": "47eb74bc049d4990b53983bd976ec2e9",
  "type": "USER"
}
```

### Fields
- **status** (string) - The new status of the user. Possible values: `UNVERIFIED`, `PENDING`, `VERIFIED`, `SUSPENDED`, `CLOSED`.
- **id** (string) - The unique identifier for the user.
- **type** (string) - Indicates the type of webhook received, which is `USER` for this event.
```

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

### Payment Webhook

Source: https://docs.checkbook.io/docs/api/webhooks

This webhook is generated when the status of a payment changes. It provides details about the payment's current status and ID.

```APIDOC
## Payment Webhook

### Description
This webhook is triggered when a payment's status is updated. For example, when a payment transitions from `UNPAID` to `IN_PROCESS`.

### Event Payload Example
```json
{
  "status": "IN_PROCESS",
  "id": "8b0ececd521c425db52cddf8d6930d54",
  "type": "CHECK",
  "deposit_option": "ACH"
}
```

### Fields
Key| Description  
---|---
**status** (string) - Required| Status of the payment — possible values are: `IN_PROCESS`, `PAID`, `FAILED`, `PRINTED`, `VOID`, `EXPIRED`, `MAILED`, `REFUNDED`  
**id** (string) - Required| ID of the payment  
**type** (string) - Required| Type of webhook received. For this event, it will be `CHECK`.  
**deposit_option** (string) - Optional| Payment rail used to receive the payment — possible values are: `ACH`, `MAIL`, `PRINT`, `INSTANT`, `RTP`, `WALLET`, `PAYPAL`, `VENMO`, `INTERAC`, `WIRE`, `SWIFT`  

**Note**
A `PAID` status indicates the funds have been sent to the recipient. Settlement times depend on the payment rail.
```

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

### Display Virtual Card Information

Source: https://docs.checkbook.io/docs/products/widgets

Utilize the Virtual Card widget to securely display card details to recipients. This leverages Checkbook's PCI DSS compliance for enhanced security.

```html
<html>
   <head>
      <script src="https://sandbox.checkbook.io/embed/checkbook-embed.js"></script>
   </head>
   <body>
      <script type="text/javascript">
         checkbook.account.ViewVcc({token: 'eyJhbGciOiJIUzI1NiIsImtpZCI6IjMyMDEyMzA5Yzk5ZTEzYzI0ZjE2MjAwNzIzZmZlNDMzIiwidHlwIjoiSldUIn0.eyJpZCI6ImNhNTYwZjZlOTk1OTRmNGVhNzdmNjc4ZWVlYjllYTI2In0.cQrma6ucsKq_WYtosEpg4-OEkTwxGx7mlYw_RlrC9jo',
         cardId: 'ca560f6e99594f4ea77f678eeeb9ea26',
         onSuccess: (res) => {
         },
         onError: (res) => {
         }}).render('#container');
      </script>
      <div id="container" style="width: 600px !important; height:700px !important;">
      </div>
   </body>
</html>
```

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

### Webhook Signature Verification in Go

Source: https://docs.checkbook.io/docs/api/webhooks

Verify the authenticity of incoming webhook requests using HMAC-SHA256 in Go. Ensure the request originates from Checkbook and has not been tampered with.

```go
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)

payload := "{ \"id\": \"de7ef9b5ed7945368cd9d5c84c13d86b\" }1243549809"
webhookKey :=  []byte("335b5728e25b582e88995fce207bff380")
h := hmac.New(sha256.New, webhookKey)
h.Write([]byte(payload))
signature := hex.EncodeToString(h.Sum(nil))
```

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

### Bank Account Webhook

Source: https://docs.checkbook.io/docs/api/webhooks

This webhook is generated when the status of a bank account changes, such as after successful microdeposit verification.

```APIDOC
## Bank Account Webhook

### Description
This webhook is triggered when the status of a bank account is updated. For example, when an account status changes from `DEPOSIT_ONLY` to `VERIFIED` after successful microdeposit verification.

### Event Payload Example
```json
{
  "status": "VERIFIED",
  "id": "1bc0ce5ce7cf447ca9f2dad1ee2a98ce",
  "type": "ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28"
}
```

### Fields
Key| Description  
---|---
**status** (string) - Required| Status of the account — possible values are: `VERIFIED`, `PENDING`, `INACTIVE`, `DEPOSIT_ONLY`  
**id** (string) - Required| ID of the account  
**type** (string) - Required| Type of webhook received. For this event, it will be `ACCOUNT`.  
**user_id** (string) - Required| ID of the user associated with the account.
```

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

### Multi-party CSV Template for Bulk Payments

Source: https://docs.checkbook.io/docs/products/payments/bulk

This CSV format supports sending payments to multiple recipients per transaction. Include columns for Recipient 1 Name, Recipient 1 Address, Recipient 2 Name, Recipient 2 Address, Amount, Check Number (optional), and Description.

```csv
Name,Address,Name,Address,Amount,Check Number,Description
Dwight Schrute,dwight@dundermifflin.com,Angela Martin,angela@dundermifflin.com,1234.56,1001,Party Planning Committee
```