# Get Crypto Balance
Source: https://docs.carbn.xyz/api-reference/account-management/get-crypto-balance

/api-reference/openapi.json get /payment/api/v1/offramp-audit/crypto-balance/{crypto}/{blockchain}/{user_id}
Get the crypto balance for a user in USD. Returns a decimal number representing the balance.



# Register Destination Account
Source: https://docs.carbn.xyz/api-reference/account-management/register-destination-account

/api-reference/openapi.json post /payment/api/v1/accounts/register
Register a new destination account (bank account or card) for a user



# Register Wallet
Source: https://docs.carbn.xyz/api-reference/account-management/register-wallet

/api-reference/openapi.json post /payment/api/v1/wallets/register
Register a new wallet for a user



# Get Offramp Transaction Status
Source: https://docs.carbn.xyz/api-reference/audit-&-reporting/get-offramp-transaction-status

/api-reference/openapi.json get /payment/api/v1/offramp-audit/status/{transaction_id}
Get the current status of a specific offramp transaction by its ID



# Get Onramp Audit
Source: https://docs.carbn.xyz/api-reference/audit-&-reporting/get-onramp-audit

/api-reference/openapi.json get /payment/api/v1/onramp-audit/{wallet_id}
Get audit information for onramp transactions for a specific wallet



# Get Onramp Transaction Status
Source: https://docs.carbn.xyz/api-reference/audit-&-reporting/get-onramp-transaction-status

/api-reference/openapi.json get /payment/api/v1/onramp-audit/status/{transaction_id}
Get the current status of a specific onramp transaction by its ID



# Authentication
Source: https://docs.carbn.xyz/api-reference/authentication

Learn how to authenticate with the Carbn Connect API

Carbn uses API keys to authenticate your requests. You can generate them from the [dashboard](https://dashboard.carbnconnect.com/app/keys).

<Warning>
  API keys are shown only once at the time of creation. Be sure to copy and store them securely, they cannot be retrieved later.
</Warning>

### How Authentication Works

* Pass your API key in the `x-api-key` header using HTTP Basic Auth.
* No username or password is required, just the API key.
* All requests must be made over HTTPS; requests over plain HTTP are rejected.
* Invalid or missing keys will return a 401 Unauthorized.

<Danger>
  Keep your API keys secure. They grant full access to your account and should never be shared publicly or within internal tools like Slack or Dashboards.
</Danger>

### Sample Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/onboarding/api/v1/users/all' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/users/all', {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
  }

  response = requests.get(
      'https://api.carbnconnect.com/onboarding/api/v1/users/all',
      headers=headers
  )
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.carbnconnect.com/onboarding/api/v1/users/all"))
      .header("Content-Type", "application/json")
      .header("x-api-key", "<api-key>")
      .GET()
      .build();

  HttpResponse<String> response = client.send(request, 
      HttpResponse.BodyHandlers.ofString());
  ```
</CodeGroup>


# Create Custody Wallet
Source: https://docs.carbn.xyz/api-reference/custody-wallet/create-custody-wallet

/api-reference/openapi.json post /payment/api/v1/custody-wallet
Create a Carbn custody wallet for a user on the specified chain



# Custody Wallet Transfer
Source: https://docs.carbn.xyz/api-reference/custody-wallet/custody-wallet-transfer

/api-reference/openapi.json post /payment/api/v1/custody-wallet/transfer
Initiate a transfer from a Carbn custody wallet to an external address



# Get Custody Wallet
Source: https://docs.carbn.xyz/api-reference/custody-wallet/get-custody-wallet

/api-reference/openapi.json get /payment/api/v1/custody-wallet/{custody_wallet_id}
Get details of a Carbn custody wallet by ID



# Get Custody Wallet Transactions
Source: https://docs.carbn.xyz/api-reference/custody-wallet/get-custody-wallet-transactions

/api-reference/openapi.json get /payment/api/v1/custody-wallet/{custody_wallet_id}/transactions
Get paginated list of transactions for a custody wallet



# Get Custody Wallet Transfer Status
Source: https://docs.carbn.xyz/api-reference/custody-wallet/get-custody-wallet-transfer-status

/api-reference/openapi.json get /payment/api/v1/custody-wallet/transfer/{transaction_id}
Get the status of a custody wallet transfer by transaction ID



# Get Total Custody Wallet Balances
Source: https://docs.carbn.xyz/api-reference/custody-wallet/get-total-custody-wallet-balances

/api-reference/openapi.json get /payment/api/v1/custody-wallet/total-balances
Get aggregated balances across all custody wallets for all supported cryptocurrencies



# Error Handling
Source: https://docs.carbn.xyz/api-reference/errors

Understand Carbn API error codes, responses, and handling

## Error Response Structure

All API errors follow a consistent JSON structure with detailed information to help you debug issues. Here is a sample error response:

<CodeGroup>
  ```json Error Response Structure theme={null}
  {
      "code": "4300",
      "httpMethod": "PATCH", 
      "message": "Insufficient permissions to access resource",
      "path": "/onboarding/api/v1/users/all",
      "requestId": "46a7ad4b-c315-441c-ad2c-473f4075e1b5",
      "resourcePath": "/onboarding/api/v1/{proxy+}"
  }
  ```
</CodeGroup>

#### Response Fields

<Accordion title="Field Definitions" icon="list">
  | Field              | Type     | Description                                  | Example                                  |
  | :----------------- | :------- | :------------------------------------------- | :--------------------------------------- |
  | **`code`**         | `string` | 🏷️ Internal error code for categorization   | `"4300"`, `"4030"`                       |
  | **`httpMethod`**   | `string` | 🌐 HTTP method used in the request           | `"GET"`, `"POST"`, `"PATCH"`             |
  | **`message`**      | `string` | 💬 Human-readable error description          | `"Missing authentication token"`         |
  | **`path`**         | `string` | 🛣️ Exact API endpoint path that was called  | `"/onboarding/api/v1/users/all"`         |
  | **`requestId`**    | `string` | 🔍 Unique identifier for this request (UUID) | `"46a7ad4b-c315-441c-ad2c-473f4075e1b5"` |
  | **`resourcePath`** | `string` | ⚙️ AWS API Gateway resource path pattern     | `"/onboarding/api/v1/{proxy+}"`          |

  <Note>
    **Pro Tip:** The `requestId` is your golden ticket for support - it's like a fingerprint for your specific API call!
  </Note>
</Accordion>

<Info>
  Always include the `requestId` when contacting support - it helps us quickly locate your specific request in our logs.
</Info>

<Warning>
  The `code` field is our internal error classification system. Use this along with the HTTP status code to programmatically handle different error scenarios.
</Warning>

***

## Quick Reference

<Columns>
  <Card title="Most Common" icon="circle-alert">
    **Missing API Key (4030)**

    Add `X-API-Key` header to your request
  </Card>

  <Card title="Format Issue" icon="key">
    **Invalid Format (4100)**

    API key must be exactly 32 alphanumeric characters
  </Card>
</Columns>

<Columns>
  <Card title="Not Found" icon="search">
    **API Key Not Found (4101)**

    Double-check your API key is correct
  </Card>

  <Card title="Permissions" icon="shield">
    **Insufficient Permissions (4300)**

    Contact support for permission updates
  </Card>
</Columns>

***

## Complete Error Reference

### Authentication Errors

<AccordionGroup>
  <Accordion title="[4030] - Missing API Key" icon="key">
    | Response Field  | Details                                       |
    | :-------------- | :-------------------------------------------- |
    | **HTTP Status** | `403 Forbidden`                               |
    | **Message**     | Missing authentication token                  |
    | **Root Cause**  | No `X-API-Key` header provided in the request |
    | **Impact**      | 🔴 High - Blocks all API access               |
    | **Fix Time**    | ⚡ \< 1 minute                                 |

    <Note>
      Add the `X-API-Key` header with your API key to all requests.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl -H "X-API-Key: <api-key>" \
           -H "Content-Type: application/json" \
           https://api.carbnconnect.com/onboarding/api/v1/users/all
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/users/all', {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': '<api-key>'
        }
      });
      ```

      ```python Python theme={null}
      import requests

      headers = {
          'Content-Type': 'application/json',
          'X-API-Key': '<api-key>'
      }

      response = requests.get(
          'https://api.carbnconnect.com/onboarding/api/v1/users/all',
          headers=headers
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="[4100] - Invalid API Key Format" icon="triangle-alert">
    | Response Field  | Details                                           |
    | :-------------- | :------------------------------------------------ |
    | **HTTP Status** | `403 Forbidden`                                   |
    | **Message**     | Invalid API key format                            |
    | **Root Cause**  | API key is not exactly 32 alphanumeric characters |
    | **Impact**      | 🔴 High - Authentication fails                    |
    | **Fix Time**    | ⚡ \< 30 seconds                                   |

    <Warning>
      Verify API Key format requirements - API keys are case-sensitive and must be exactly 32 characters long (A-Z, a-z, 0-9)
    </Warning>
  </Accordion>

  <Accordion title="[4101] - API Key Not Found" icon="search">
    | Response Field  | Details                             |
    | :-------------- | :---------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                  |
    | **Message**     | API key not found                   |
    | **Root Cause**  | API key doesn't exist in our system |
    | **Impact**      | 🔴 High - Complete access denial    |
    | **Fix Time**    | ⏱️ 2-3 minutes                      |

    <Callout icon="key">
      Verify your API key is correct or generate a new API key from the [dashboard](https://dashboard.carbnconnect.com).
    </Callout>
  </Accordion>

  <Accordion title="[4102] - API Key Expired" icon="clock">
    | Response Field  | Details                                |
    | :-------------- | :------------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                     |
    | **Message**     | API key has expired                    |
    | **Root Cause**  | API key has passed its expiration date |
    | **Impact**      | 🔴 High - All requests blocked         |
    | **Fix Time**    | ⏱️ 2-3 minutes                         |

    <Note>
      Generate a new API key from your [dashboard](https://dashboard.carbnconnect.com).
    </Note>

    <Info>
      **Pro Tip:** Set up API key rotation reminders to avoid service interruptions
    </Info>
  </Accordion>

  <Accordion title="[4103] - API Key Inactive" icon="ban">
    | Response Field  | Details                                   |
    | :-------------- | :---------------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                        |
    | **Message**     | API key is inactive                       |
    | **Root Cause**  | API key has been suspended or deactivated |
    | **Impact**      | 🔴 High - Account-level issue             |
    | **Fix Time**    | ⏰ 1-24 hours (support dependent)          |

    <Danger>
      **Account Issue:** This usually indicates a billing or compliance concern. Contact [support](mailto:support@carbn.xyz) immediately.
    </Danger>
  </Accordion>
</AccordionGroup>

### Authorization Errors

<AccordionGroup>
  <Accordion title="[4300] - Insufficient Permissions" icon="shield-alert">
    | Response Field  | Details                                                       |
    | :-------------- | :------------------------------------------------------------ |
    | **HTTP Status** | `403 Forbidden`                                               |
    | **Message**     | Insufficient permissions to access resource                   |
    | **Root Cause**  | Your API key lacks the required permissions for this endpoint |
    | **Impact**      | 🟡 Medium - Specific endpoints blocked                        |
    | **Fix Time**    | ⏰ 2-24 hours (support dependent)                              |

    <Note>
      **Permission Levels:** Different endpoints require different permission levels. Check the specific endpoint documentation for required permissions.
    </Note>

    <Info>
      **Common Cause:** This often happens when using a read-only API key for write operations (POST, PATCH, DELETE)
    </Info>
  </Accordion>
</AccordionGroup>

***

## HTTP Status Code Reference

<AccordionGroup>
  <Accordion title="Success Codes (2xx)" icon="circle-check-big">
    | Status Code | Status Name | Description                             | Action Required    |
    | :---------- | :---------- | :-------------------------------------- | :----------------- |
    | **`200`**   | **OK**      | Your request has completed successfully | No action required |
    | **`201`**   | **Created** | Resource created successfully           | No action required |

    <Check>
      **2xx responses** indicate successful requests. Your API call worked as expected and you can proceed with the response data.
    </Check>
  </Accordion>

  <Accordion title="Client Error Codes (4xx)" icon="triangle-alert">
    | Status Code | Status Name      | Description                                  | Action Required    |
    | :---------- | :--------------- | :------------------------------------------- | :----------------- |
    | **`400`**   | **Bad Request**  | Request format is invalid or malformed       | Fix request syntax |
    | **`401`**   | **Unauthorized** | Authentication failed or missing credentials | Check API key      |
    | **`403`**   | **Forbidden**    | Access forbidden due to permissions          | Check permissions  |
    | **`404`**   | **Not Found**    | Resource doesn't exist or not found          | Verify resource ID |
    | **`429`**   | **Rate Limited** | Too many requests sent recently              | Wait and retry     |

    <Warning>
      **4xx errors** mean there's an issue with your request. Double-check your API key, request format, and permissions.
    </Warning>
  </Accordion>

  <Accordion title="Server Error Codes (5xx)" icon="server-crash">
    | Status Code | Status Name             | Description                     | Action Required          |
    | :---------- | :---------------------- | :------------------------------ | :----------------------- |
    | **`500`**   | **Internal Error**      | Something went wrong on our end | Contact support          |
    | **`502`**   | **Bad Gateway**         | Gateway/proxy error             | Retry or contact support |
    | **`503`**   | **Service Unavailable** | Temporary service issue         | Wait and retry           |

    <Danger>
      **5xx errors** are on us! If you see these consistently, please contact support with your `requestId`.
    </Danger>
  </Accordion>
</AccordionGroup>

***

## Getting Help

<Columns>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz">
    When contacting support, please include:
    <Check>**Request ID** from the error response</Check>
    <Check>**Endpoint** you were trying to access</Check>
    <Check>**Error** response details available</Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>


# Get Carbn Currency Exchange Rate
Source: https://docs.carbn.xyz/api-reference/exchange/get-carbn-currency-exchange-rate

/api-reference/openapi.json get /payment/api/v1/exchange/currency-rates/carbn
Get the current exchange rate from source currency to target currency using Carbn's rates



# Get Open Banking Institutions
Source: https://docs.carbn.xyz/api-reference/open-banking/get-open-banking-institutions

/api-reference/openapi.json post /payment/api/v1/transfers/get-institutes
Fetch supported banking institutions for one or more countries. Supports two modes: browse mode (paginated list using `count` and `offset`) and search mode (filter by institution name using `query`). When `query` is provided, `count` and `offset` are not required.



# Get Open Banking Payment Status
Source: https://docs.carbn.xyz/api-reference/open-banking/get-open-banking-payment-status

/api-reference/openapi.json get /payment/api/v1/ob/{payment_id}
Get the status and details of an Open Banking payment by payment ID



# Accept Offramp Quote
Source: https://docs.carbn.xyz/api-reference/payments/accept-offramp-quote

/api-reference/openapi.json post /payment/api/v1/offramp/accept-quote
Accept a quote and initiate the offramp transfer



# Get Offramp Quote
Source: https://docs.carbn.xyz/api-reference/payments/get-offramp-quote

/api-reference/openapi.json post /payment/api/v1/offramp/get-quote
Get a quote for converting crypto to fiat and sending to a registered destination account



# Initiate Offramp
Source: https://docs.carbn.xyz/api-reference/payments/initiate-offramp

/api-reference/openapi.json post /payment/api/v1/offramp
Initiate an offramp transfer. Returns a cryptocurrency deposit address where users should send their crypto. Once crypto is deposited, it will be converted to fiat and sent to the registered destination account.



# Initiate Offramp Payout
Source: https://docs.carbn.xyz/api-reference/payments/initiate-offramp-payout

/api-reference/openapi.json post /payment/api/v1/offramp/payout
Initiate a payout after crypto has been deposited to the offramp address. This converts the deposited crypto to fiat and sends it to the registered destination account.



# Onramp Transfer
Source: https://docs.carbn.xyz/api-reference/payments/onramp-transfer

/api-reference/openapi.json post /payment/api/v1/transfers/onramp
Initiate a new onramp transfer



# Create Payout
Source: https://docs.carbn.xyz/api-reference/payouts/create-payout

/api-reference/openapi.json post /payment/api/v1/payout
Create a local currency payout to a user's bank account using their available balance.



# Get Payout Balances
Source: https://docs.carbn.xyz/api-reference/payouts/get-payout-balances

/api-reference/openapi.json get /payment/api/v1/payout/balances/{user_id}
Retrieve available payout balances for a user, grouped by currency.



# Get Payout Status
Source: https://docs.carbn.xyz/api-reference/payouts/get-payout-status

/api-reference/openapi.json get /payment/api/v1/payout/{payout_id}
Retrieve the current status and details of a payout.



# Create User Onboarding Session
Source: https://docs.carbn.xyz/api-reference/user-management/create-user-onboarding-session

/api-reference/openapi.json post /onboarding/api/v1/users/session
Create a new user onboarding session and generate a hosted KYC link. This endpoint is used for the hosted KYC flow where users complete verification through a pre-built compliance interface. The returned onboarding URL redirects users to complete their KYC verification.



# Generate User Consent
Source: https://docs.carbn.xyz/api-reference/user-management/generate-user-consent

/api-reference/openapi.json post /onboarding/api/v1/tnc
Record user acceptance of terms and conditions and generate a consent ID



# Get All Users
Source: https://docs.carbn.xyz/api-reference/user-management/get-all-users

/api-reference/openapi.json get /onboarding/api/v1/users/all
Get a list of all users in the system



# Get User Details
Source: https://docs.carbn.xyz/api-reference/user-management/get-user-details

/api-reference/openapi.json get /onboarding/api/v1/users/{user_id}
Retrieve detailed information about a user including their KYC status, verification state, and any requirements due. For comprehensive guides on handling user statuses and rejection reasons, see our [User Status Documentation](/documentation/developer-platform/users/compliance/user-status) and [Rejection Reasons Guide](/documentation/developer-platform/users/compliance/rejection-reasons).



# Update User
Source: https://docs.carbn.xyz/api-reference/user-management/update-user

/api-reference/openapi.json put /onboarding/api/v1/users/{user_id}
Update user information. All fields are optional - only include fields that need to be updated.



# User Onboarding
Source: https://docs.carbn.xyz/api-reference/user-management/user-onboarding

/api-reference/openapi.json post /onboarding/api/v1/users
Create a new user with KYC information



# Register Webhook
Source: https://docs.carbn.xyz/api-reference/webhook-management/register-webhook

/api-reference/openapi.json post /onboarding/api/v1/webhooks
Register a new webhook endpoint to receive event notifications. Webhooks are created with `status: "disabled"` by default and must be enabled using the PUT endpoint. For comprehensive webhook setup and verification guides, see [Configure Webhooks](/documentation/getting-started/configure-webhook) and [Webhook Verification](/documentation/developer-platform/monitoring/webhook-verification).



# Trigger Webhook Event
Source: https://docs.carbn.xyz/api-reference/webhook-management/trigger-webhook-event

/api-reference/openapi.json post /onboarding/api/v1/webhooks/trigger/{webhook_id}
Manually trigger a webhook event for testing purposes using the webhook event's unique ID



# Update Webhook
Source: https://docs.carbn.xyz/api-reference/webhook-management/update-webhook

/api-reference/openapi.json put /onboarding/api/v1/webhooks
Update an existing webhook's URL and status. Webhooks are created with 'disabled' status by default and must be enabled using this endpoint.

**Important:** The event category cannot be changed after webhook creation. Only the URL and status can be updated.

**Default Behavior:**
- All webhooks are created with `status: "disabled"`
- Use this endpoint to set `status: "enabled"` to start receiving events
- URL can be updated to change the webhook destination



# Changelog
Source: https://docs.carbn.xyz/changelog/overview

Stay up to date with the latest changes and improvements to Carbn Connect

# Changelog

Keep track of all changes, improvements, and new features added to the Carbn Connect API and platform.

## How to Stay Updated

* **RSS Feed**: Subscribe to our changelog RSS feed
* **Webhook Notifications**: Get notified of breaking changes via webhooks
* **Email Updates**: Subscribe to our developer newsletter

<Card title="Subscribe to Updates" icon="bell" href="mailto:developers@carbnconnect.com?subject=Subscribe to Changelog">
  Get notified when we release new features and updates
</Card>

## Version History

<Card title="v1.0.0 - Initial Release" icon="rocket" href="/changelog/v1-0-0">
  Our initial API release with core functionality
</Card>

## Upcoming Features

We're constantly working on new features and improvements. Here's what's coming soon:

### Q1 2025

* **Multi-currency Support**: Support for additional stablecoins
* **Batch Processing**: Process multiple transactions in a single request
* **Advanced Analytics**: Enhanced reporting and analytics dashboard

### Q2 2025

* **Enhanced API endpoints**: Additional payment corridor coverage
* **Recurring Payments**: Support for subscription and recurring payment flows
* **Enhanced Webhooks**: More granular webhook events and filtering

## Breaking Changes Policy

We take backward compatibility seriously. When we do need to make breaking changes:

1. **Advance Notice**: At least 90 days notice for breaking changes
2. **Migration Guides**: Detailed guides to help you migrate
3. **Sunset Timeline**: Clear timeline for deprecated features
4. **Support**: Dedicated support during migration periods

## API Versioning

Our API uses date-based versioning in the URL path:

* Current version: `v1.0.0`
* Version format: `vMAJOR.MINOR.PATCH`

### Version Support

* **Current Version**: Full support and active development
* **Previous Version**: Bug fixes and security updates only
* **Deprecated Versions**: 12-month sunset period with advance notice

## Feedback

Have feedback on our API or suggestions for new features?

<Card title="Share Your Feedback" icon="comment" href="mailto:feedback@carbnconnect.com">
  We'd love to hear from you
</Card>


# Payouts
Source: https://docs.carbn.xyz/documentation/developer-platform/monitoring/payouts

Integrate fiat payouts to bank accounts using Carbn

Payouts let you send funds from your Carbn balance to a user's bank account in local currency.

Key API reference pages:

* [Create Payout](/api-reference/payouts/create-payout)
* [Get Payout](/api-reference/payouts/get-payout)
* [Get Payout Balances by User](/api-reference/payouts/get-payout-balances-by-user)

***

## Prerequisites

Before you implement payouts, make sure:

* **Users are onboarded** and KYC‑verified (status `active`).
* **Funds are available** in the payout currency for the user.
* **API key** is configured with payment permissions (see [Authentication](/api-reference/authentication)).
* The destination **bank account or wallet** (for example INSTAPAY) is supported for the corridor.

***

## Payout lifecycle

<Steps>
  <Step title="Check the user’s payout balance">
    API Reference: **[/payouts/get-payout-balances-by-user](/api-reference/payouts/get-payout-balances-by-user)**

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/balances/{user_id}' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key>'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://api.carbnconnect.com/payment/api/v1/payout/balances/{user_id}',
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': '<api-key>',
          },
        }
      );

      const { balances } = await response.json();
      // e.g. [{ currency: 'PHP', amount: '506.54' }]
      ```
    </CodeGroup>

    Typical response (trimmed):

    ```json theme={null}
    {
      "balances": [
        {
          "currency": "PHP",
          "amount": "506.54"
        }
      ]
    }
    ```
  </Step>

  <Step title="Create a payout">
    API Reference: **[/payouts/create-payout](/api-reference/payouts/create-payout)**

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.carbnconnect.com/payment/api/v1/payout' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key>' \
        --data '{
          "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
          "currency": "php",
          "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
          "amount": "20",
          "recipient_details": {
            "bank_name": "gotyme",
            "account_holder_name": "Chelsea Mae Esguerra",
            "recipient_account_number": "019794249552"
          }
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://api.carbnconnect.com/payment/api/v1/payout',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': '<api-key>',
          },
          body: JSON.stringify({
            user_id: '9973efd0-410c-4b1a-991c-5a00f1581734',
            currency: 'php',
            customer_payout_id: '491595e0-2d40-4aa3-9f3d-4e8cdd79511e',
            amount: '20',
            recipient_details: {
              bank_name: 'gotyme',
              account_holder_name: 'Chelsea Mae Esguerra',
              recipient_account_number: '019794249552',
            },
          }),
        }
      );

      const payout = await response.json();
      // Save payout.id and customer_payout_id for reconciliation
      ```
    </CodeGroup>

    Successful response (key fields):

    ```json theme={null}
    {
      "id": "052471e2-1819-448f-ad74-03f237c1dfd6",
      "currency": "php",
      "rail": "INSTAPAY",
      "amount": 20,
      "status": "INITIATED",
      "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
      "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
      "rail_fee": 10,
      "account_details": {
        "bank_name": "gotyme",
        "account_holder_name": "Chelsea Mae Esguerra",
        "recipient_account_number": "019794249552"
      }
    }
    ```
  </Step>

  <Step title="Track payout status">
    API Reference: **[/payouts/get-payout](/api-reference/payouts/get-payout)**

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.carbnconnect.com/payment/api/v1/payout/{payout_id}' \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: <api-key>'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://api.carbnconnect.com/payment/api/v1/payout/{payout_id}',
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': '<api-key>',
          },
        }
      );

      const payout = await response.json();
      // payout.status === 'INITIATED' | 'PAYOUT_PROCESSED' | 'FAILED' (depending on rail)
      ```
    </CodeGroup>

    Example (processed):

    ```json theme={null}
    {
      "id": "052471e2-1819-448f-ad74-03f237c1dfd6",
      "currency": "php",
      "rail": "INSTAPAY",
      "reference": "051567",
      "amount": 20.0,
      "status": "PAYOUT_PROCESSED",
      "user_id": "9973efd0-410c-4b1a-991c-5a00f1581734",
      "customer_payout_id": "491595e0-2d40-4aa3-9f3d-4e8cdd79511e",
      "rail_fee": 10.0,
      "account_details": {
        "bank_name": "gotyme",
        "account_holder_name": "Chelsea Mae Esguerra",
        "recipient_account_number": "019794249552"
      },
      "created_at": "2026-03-13T16:32:17.604935Z",
      "updated_at": "2026-03-13T16:32:46.364880Z"
    }
    ```
  </Step>

  <Step title="Subscribe to payout webhooks">
    For real-time updates, configure a webhook with the `PAYOUT` event category (see [Configure Webhooks](/documentation/getting-started/configure-webhook)).

    When enabled, Carbn will send payout status changes (for example from `INITIATED` to `PAYOUT_PROCESSED`) to your webhook endpoint.
  </Step>
</Steps>

***

## Payout statuses

<AccordionGroup>
  <Accordion title="INITIATED" icon="clock">
    <Info>Payout has been created and queued for processing by the rail.</Info>
  </Accordion>

  <Accordion title="PAYOUT_PROCESSED" icon="circle-check">
    <Check>Rail has confirmed the payout; funds are considered delivered.</Check>
  </Accordion>

  <Accordion title="FAILED" icon="triangle-alert">
    <Danger>Payout could not be completed (for example, rail or account error); check logs and webhooks for details.</Danger>
  </Accordion>
</AccordionGroup>


# Transfer Status
Source: https://docs.carbn.xyz/documentation/developer-platform/monitoring/transfer-status

Monitor and track transfer states throughout the complete payment lifecycle

Understanding transfer statuses is crucial for providing users with accurate information about their payments and handling edge cases appropriately. This guide covers all possible transfer states and how to monitor them effectively.

## Transfer Lifecycle

All transfers in Carbn Connect follow a predictable lifecycle with specific states that indicate the current stage of processing:

<Steps>
  <Step title="Initiation">
    Transfer is created and awaiting funds or processing
  </Step>

  <Step title="Processing">
    Funds are being moved through the payment system
  </Step>

  <Step title="Completion">
    Transfer reaches final state (success, failure, or requires action)
  </Step>
</Steps>

***

## Transfer States

The transfer status indicates the current state of a transfer. Here are all possible states:

<AccordionGroup>
  <Accordion title="awaiting_funds" icon="clock">
    **Description**: Carbn is waiting to receive funds from the user before processing the transfer.

    **Applies to**:

    * SEPA Payments
    * Wire transfers
    * ACH pushes
    * Virtual account transfers

    **Next Steps**: Wait for user to send funds or complete payment flow.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "awaiting_funds",
        "created_at": "2024-01-01T10:00:00Z",
        "source_currency": "eur",
        "amount": 100
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="funds_received" icon="circle-check">
    **Description**: Carbn has received the funds and is preparing to move them on the user's behalf.

    **Duration**: Usually seconds to a few minutes

    **What's happening**: Internal processing, validation, and preparation for onward transfer.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "funds_received",
        "updated_at": "2024-01-01T10:05:00Z",
        "source_currency": "eur",
        "amount": 100
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="in_review" icon="clock">
    **Description**: A temporary state triggered when transfer data needs further confirmation.

    **Duration**: Typically resolves in seconds; otherwise, Carbn will reach out within 24 hours.

    **Action Required**: Wait for automatic resolution or contact support if extended.

    <Warning>
      This is a rare state that usually resolves automatically. If a transfer remains in this state for more than 24 hours, contact support.
    </Warning>
  </Accordion>

  <Accordion title="payment_submitted" icon="arrow-right">
    **Description**: Carbn has initiated the payment and is awaiting confirmation.

    **Duration varies by payment rail**:

    * **Crypto**: Minutes
    * **Wires**: Hours
    * **ACH**: Days

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "payment_submitted",
        "updated_at": "2024-01-01T10:06:00Z",
        "payment_rail": "crypto",
        "estimated_completion": "2024-01-01T10:15:00Z"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="payment_processed" icon="circle-check-big">
    **Description**: The transfer is complete and funds have been successfully delivered to the destination.

    **Final State**: This is a successful completion state.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "payment_processed",
        "completed_at": "2024-01-01T10:12:00Z",
        "final_amount": 95.50,
        "destination_confirmed": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Exception States

<AccordionGroup>
  <Accordion title="undeliverable" icon="circle-x">
    **Description**: Carbn was unable to deliver funds due to an issue like an invalid account or unsupported asset at the destination.

    **Common Causes**:

    * Invalid destination wallet address
    * Unsupported asset at destination
    * Destination account closed or frozen

    **Action Required**: Check destination details and retry with correct information.
  </Accordion>

  <Accordion title="returned" icon="arrow-left">
    **Description**: The payment was sent but failed. Funds have returned to Carbn and a refund to the sender is underway.

    **What happens next**: Automatic refund process initiated to original sender.
  </Accordion>

  <Accordion title="refunded" icon="arrow-left-right">
    **Description**: The transfer was refunded back to the original sender.

    **Final State**: This is a completion state where funds are returned.
  </Accordion>

  <Accordion title="canceled" icon="ban">
    **Description**: The transfer was canceled. This can only happen from the `awaiting_funds` state.

    **How to cancel**: Contact support to cancel a transfer in `awaiting_funds` status.

    <Note>
      Transfers can only be canceled while in `awaiting_funds` status. Once funds are received, cancellation is no longer possible.
    </Note>
  </Accordion>

  <Accordion title="error" icon="triangle-alert">
    **Description**: A problem occurred that blocked processing. This typically requires manual review or developer action.

    **Action Required**: Contact support with transfer details for investigation.
  </Accordion>
</AccordionGroup>

***

## Open Banking Payment Status

When using Open Banking for fund collection, the standard `awaiting_funds` status is replaced by specific Open Banking payment statuses. These statuses track the payment authorization and execution process through the banking system.

### Open Banking Flow

Open Banking payments follow this progression:

```
PAYMENT_STATUS_INPUT_NEEDED → PAYMENT_STATUS_AUTHORISING → PAYMENT_STATUS_INITIATED → PAYMENT_STATUS_EXECUTED → funds_received
```

<AccordionGroup>
  <Accordion title="PAYMENT_STATUS_INPUT_NEEDED" icon="user-check">
    **Description**: Awaiting user input to begin the payment authorization process.

    **What's happening**: User has received the Open Banking link but hasn't started the authorization flow yet.

    **Duration**: Depends on user action - no time limit

    **User Action Required**: User needs to click the Open Banking link and begin authorization with their bank.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "payment_status": "PAYMENT_STATUS_INPUT_NEEDED",
        "created_at": "2024-01-01T10:00:00Z",
        "payment_method": "open_banking"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_AUTHORISING" icon="shield-check">
    **Description**: User is in the process of authorizing the payment with their bank.

    **What's happening**: User has started the authorization flow and is providing credentials/consent to their bank.

    **Duration**: Typically a few minutes while user completes bank authorization

    **Next Steps**: Wait for user to complete authorization or abandon the process.
  </Accordion>

  <Accordion title="PAYMENT_STATUS_INITIATED" icon="arrow-right">
    **Description**: Payment has been authorized and is in transit through the banking system.

    **What's happening**: User successfully authorized the payment, and it's being processed by the bank.

    **Duration**: Usually minutes to hours depending on the bank

    **Possible Outcomes**: Can progress to `EXECUTED`, `FAILED`, `BLOCKED`, or `REJECTED`
  </Accordion>

  <Accordion title="PAYMENT_STATUS_EXECUTED" icon="circle-check-big">
    **Description**: Funds have successfully left the payer's account.

    **Final Success Status**: After this status, the transfer moves to `funds_received` and follows the standard transfer flow.

    **What's Next**: Transfer continues with normal processing (`funds_received` → `payment_submitted` → `payment_processed`)
  </Accordion>
</AccordionGroup>

### Open Banking Exception States

<AccordionGroup>
  <Accordion title="PAYMENT_STATUS_FAILED" icon="triangle-alert">
    **Description**: System error occurred during payment processing (retryable).

    **Common Causes**:

    * Bank system downtime
    * Temporary Open Banking service issues
    * Network connectivity problems

    **Action Required**: Create a new Open Banking link and retry the payment process.

    <Warning>
      This is a retryable error. The payment can be attempted again with a fresh Open Banking link.
    </Warning>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_BLOCKED" icon="ban">
    **Description**: Payment blocked by Plaid due to compliance or risk issues (rare, retryable).

    **What happened**: Plaid's risk management system flagged the payment for review.

    **Action Required**: Create a new Open Banking link and retry. If the issue persists, contact support.

    <Note>
      This is rare but can happen due to risk assessment algorithms. Usually resolves with a new attempt.
    </Note>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_REJECTED" icon="circle-x">
    **Description**: Payment was rejected by the bank (terminal status).

    **What happened**: The bank declined the payment after initial authorization.

    **Important**: If funds were debited, the bank will automatically return them to the source account.

    **Final State**: This is a terminal status - the payment cannot be retried with the same link.
  </Accordion>

  <Accordion title="PAYMENT_STATUS_CANCELLED" icon="user-x">
    **Description**: The end user cancelled the payment during authorization (terminal status).

    **What happened**: User actively cancelled the payment process while authorizing with their bank.

    **User Action**: User chose to abandon the payment flow before completion.

    **Final State**: This is a terminal status - the payment cannot be retried with the same link.
  </Accordion>
</AccordionGroup>

### Open Banking Status Transitions

<Info>
  **Key Points**:

  * Open Banking statuses replace `awaiting_funds` in the standard flow
  * Only `PAYMENT_STATUS_EXECUTED` leads to `funds_received`
  * Failed, blocked, or rejected statuses require creating a new Open Banking link
  * The flow can move backwards (e.g., `INITIATED` → `FAILED`)
</Info>

**Complete Flow Diagram**:

```
PAYMENT_STATUS_INPUT_NEEDED
    ↓
PAYMENT_STATUS_AUTHORISING
    ↓
PAYMENT_STATUS_INITIATED → PAYMENT_STATUS_FAILED (retry needed)
    ↓                   → PAYMENT_STATUS_BLOCKED (retry needed)  
    ↓                   → PAYMENT_STATUS_REJECTED (terminal)
PAYMENT_STATUS_EXECUTED
    ↓
funds_received → payment_submitted → payment_processed
```

***

## Monitoring Transfer Status

### Check Individual Transfer Status

Monitor specific transfers using the status endpoints:

<CodeGroup>
  ```bash On-Ramp Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Onramp Transaction Status API Reference](/api-reference/audit-reporting/get-onramp-transaction-status)

  ```bash Off-Ramp Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/offramp-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Offramp Transaction Status API Reference](/api-reference/audit-reporting/get-offramp-transaction-status)

  ```bash FX Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/fx-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Transfer Transaction Status API Reference](/api-reference/audit-reporting/get-transfer-transaction-status)
</CodeGroup>

### Bulk Transfer Monitoring

Get status for multiple transfers by user:

<CodeGroup>
  ```bash User On-Ramp History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/{wallet_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Onramp Audit API Reference](/api-reference/audit-reporting/get-onramp-audit)

  ```bash User Off-Ramp History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/offramp-audit/{user_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Offramp Audit API Reference](/api-reference/audit-reporting/get-offramp-audit)

  ```bash User FX History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/fx-audit/{user_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Transfer Audit API Reference](/api-reference/audit-reporting/get-transfer-audit)
</CodeGroup>

***

## State Progression Rules

<Info>
  **Important**: Transfers always progress forward through states and never go backwards:

  `awaiting_funds` → `funds_received` → `payment_submitted` → `payment_processed`
</Info>

***

## What's Next?

<CardGroup>
  <Card title="Configure Webhooks" icon="webhook" href="/documentation/getting-started/configure-webhook">
    Set up real-time notifications for status changes
  </Card>

  <Card title="Webhook Verification" icon="shield-check" href="/documentation/developer-platform/monitoring/webhook-verification">
    Learn how to verify webhook authenticity
  </Card>
</CardGroup>

## Getting Help

<Columns>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz">
    When contacting support, please include:
    <Check>**Transaction ID** of the payment</Check>
    <Check>**Wallet ID** If transfer ID not available</Check>
    <Check>**Transfer type** (FX, on-ramp, off-ramp)</Check>
    <Check>**Error messages** or **status codes** </Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>


# Webhook Verification
Source: https://docs.carbn.xyz/documentation/developer-platform/monitoring/webhook-verification

Verify webhook authenticity using RSA signature verification

Carbn includes a `X-Webhook-Signature` header with each webhook delivery for authenticity verification. This ensures that webhook events are genuinely from Carbn and haven't been tampered with.

## Signature Format

The header value is a base64 encoded RSA signature: `<base64_encoded_signature>`

## Verification Process

1. **Extract the signature** from the `X-Webhook-Signature` header
2. **Decode the signature** using base64 decoding to get signature bytes
3. **Verify the signature** using Carbn's public key and the raw HTTP request body

## Complete HTTP Request Example

<CodeGroup>
  ```http HTTP Request theme={null}
  POST /webhooks/carbn HTTP/1.1
  Host: your-app.com
  Content-Type: application/json
  User-Agent: Java/17.0.14
  X-Webhook-Event-Id: 1389bf11-20e2-44fe-8650-1e8ccfd9ba42
  X-Webhook-Id: f79bc473-d45d-4026-86ec-864d4d047905
  X-Webhook-Signature: lrmZCA323EV0oWMj9KZVcw5zEfeZzZSOmAKpcgzqPPF...

  {"status": "PAYMENT_PROCESSED", "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c", "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"}
  ```
</CodeGroup>

## Security Best Practices

1. **Always verify webhook signatures** using RSA public key verification
2. **Use HTTPS endpoints** with valid certificates
3. **Implement idempotency** using the `X-Webhook-Event-Id` header
4. **Return 200 status quickly** to avoid timeouts
5. **Store public keys securely** (use environment variables)
6. **Log webhook events** for debugging and monitoring

***

## Troubleshooting

### Common Issues

* **Webhook not receiving events**: Ensure webhook is enabled and endpoint returns 200 status
* **Signature verification fails**: Use raw request body and correct RSA public key
* **Duplicate deliveries**: Implement idempotency using `X-Webhook-Event-Id` header

### Testing Your Webhook

You can test your webhook endpoint using the trigger webhook event endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.carbnconnect.com/onboarding/api/v1/webhooks/trigger/{webhook_id} \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

***

## What's Next?

<CardGroup>
  <Card title="Configure Webhooks" icon="webhook" href="/documentation/getting-started/configure-webhook">
    Learn how to set up and register webhooks
  </Card>
</CardGroup>

Proper webhook verification ensures the security and reliability of your integration with Carbn's payment system.


# Enhanced Due Diligence
Source: https://docs.carbn.xyz/documentation/developer-platform/users/compliance/enhanced-due-diligence

Additional verification requirements for high-risk users and increased limits

## Overview

Enhanced Due Diligence (EDD) is required for users who exceed certain transaction thresholds or present higher risk profiles. These additional verification steps ensure compliance with anti-money laundering (AML) regulations and help maintain the security of the platform.

***

## Transaction Limits

### Standard KYC Limits

Users who complete standard KYC verification can transact up to **\$10,000** without additional documentation.

### Enhanced Due Diligence Threshold

For transactions **above \$10,000**, users must complete Enhanced Due Diligence requirements.

***

## Additional Documentation Requirements

When Enhanced Due Diligence is triggered, users must provide:

<CardGroup>
  <Card title="Proof of Address" icon="house">
    Recent utility bill, bank statement, or government document showing current residential address
  </Card>

  <Card title="Source of Funds" icon="banknote">
    Documentation proving the origin of funds (employment records, business income, investment statements)
  </Card>
</CardGroup>

***

## AML Screening Questions

Users undergoing Enhanced Due Diligence must answer additional Anti-Money Laundering (AML) screening questions, including:

<AccordionGroup>
  <Accordion title="Employment & Income Verification" icon="briefcase">
    * Current occupation and employer details
    * Annual income range
    * Primary source of income
  </Accordion>

  <Accordion title="Transaction Purpose" icon="target">
    * Purpose of the transaction
    * Expected transaction frequency
    * Relationship to counterparties (if applicable)
  </Accordion>

  <Accordion title="Risk Assessment" icon="shield-check">
    * Politically Exposed Person (PEP) status
    * High-risk jurisdiction connections
    * Previous compliance issues
  </Accordion>
</AccordionGroup>

***

## Processing Time

<Info>
  **Enhanced Due Diligence Review Time**: Typically **2-5 business days** for manual review and approval.

  Users will be notified via email once their EDD review is complete.
</Info>

***

## What's Next?

<CardGroup>
  <Card title="KYC Requirements" icon="shield-check" href="/documentation/developer-platform/users/compliance/kyc-requirements">
    Review standard KYC requirements and documentation
  </Card>

  <Card title="User Status" icon="users" href="/documentation/developer-platform/users/compliance/user-status">
    Learn about user onboarding status and verification states
  </Card>
</CardGroup>


# KYC Requirements
Source: https://docs.carbn.xyz/documentation/developer-platform/users/compliance/kyc-requirements

Identity verification requirements for individuals and businesses

Carbn Connect requires identity verification to ensure compliance with regional regulatory standards. Requirements vary by jurisdiction and user type - this guide provides clear, region-specific requirements.

## Overview

All users must provide **basic identity information**. Additional requirements depend on:

* **Geographic location** (country of residence)
* **User type** (individual vs. business)
* **Transaction patterns** (volume and risk assessment)

<Info>
  **Basic Requirements**: All users must provide the following regardless of jurisdiction:

  * Full name
  * Email address
  * Date of birth
  * Country of residence
  * Residence address
</Info>

<Check icon="id-card">
  **Identity Documents** (required for all users):

  * Government-issued photo ID (passport or national ID)
</Check>

<Note icon="receipt">
  **Tax Identification** (required only in specific countries - see regional details below)
</Note>

***

## Document Requirements

Document verification is based on the individual's valid government-issued credentials from any supported jurisdiction.

<Info>
  Requirements vary by region due to different regulatory frameworks. Select your region for specific tax identification requirements:
</Info>

<AccordionGroup>
  <Accordion title="North America" icon="flag">
    <AccordionGroup>
      <Accordion title="🇺🇸 United States">
        | **Document Type**     | **Document Name**                                                     |
        | :-------------------- | :-------------------------------------------------------------------- |
        | **Identity Document** | `passport`, `national_id`, `permanent_resident_id`, `driving_license` |
        | **Tax Document**      | `itin`                                                                |

        <Info>
          **Additional Requirements:**

          * Proof of address may be required
          * New York and Alaska are currently not supported
        </Info>
      </Accordion>

      <Accordion title="🇨🇦 Canada">
        | **Document Type**     | **Document Name**                                                     |
        | :-------------------- | :-------------------------------------------------------------------- |
        | **Identity Document** | `passport`, `national_id`, `permanent_resident_id`, `driving_license` |
        | **Tax Document**      | `sin`                                                                 |
      </Accordion>

      <Accordion title="🇲🇽 Mexico">
        | **Document Type**     | **Document Name**                                                     |
        | :-------------------- | :-------------------------------------------------------------------- |
        | **Identity Document** | `passport`, `national_id`, `permanent_resident_id`, `driving_license` |
        | **Tax Document**      | `rfc`, `curp`                                                         |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Europe" icon="flag">
    <AccordionGroup>
      <Accordion title="🇪🇺 European Union (EU)">
        ### Identity Documents

        <Columns>
          <Card icon="circle-arrow-right">
            * `passport`
          </Card>

          <Card icon="circle-arrow-right">
            * `national_id`
          </Card>

          <Card icon="circle-arrow-right">
            * `permanent_resident_id`
          </Card>

          <Card icon="circle-arrow-right">
            * `driving_license`
          </Card>
        </Columns>

        ### Tax Documents for EU Countries

        <Card>
          | **Supported Country** | **Tax Document**                                                      |
          | :-------------------- | :-------------------------------------------------------------------- |
          | 🇮🇪 Ireland          | `ppsn` - Personal Public Service Number                               |
          | 🇫🇷 France           | `spi` - Social Security Number                                        |
          | 🇪🇸 Spain            | `nie` - Número de Identificación de Extranjeros                       |
          | 🇩🇪 Germany          | `steuer_id` - Steueridentifikationsnummer (Tax Identification Number) |
          | 🇳🇱 Netherlands      | `bsn` - Burgerservicenummer (Citizen Service Number)                  |
          | 🇧🇪 Belgium          | `nrn` - National Register Number                                      |
          | 🇫🇮 Finland          | `hetu` - Finnish Personal Identity Code                               |
          | 🇩🇰 Denmark          | `cpr` - Central Person Register Number                                |
          | 🇸🇪 Sweden           | `personnummer` - Personal Identity Number                             |
          | 🇵🇹 Portugal         | `nif` - Número de Identificação Fiscal                                |
          | 🇦🇹 Austria          | `si` - Social Insurance Number                                        |
          | 🇮🇹 Italy            | `cf` - Codice Fiscale                                                 |
          | 🇱🇺 Luxembourg       | `matricule` - Matricule Number                                        |
          | 🇪🇪 Estonia          | `isikukood` - Personal Identification Code                            |
          | 🇱🇹 Lithuania        | `asmens_kodas` - Personal Code                                        |
          | 🇱🇻 Latvia           | `personas_kods` - Person's Code                                       |
        </Card>

        <Info>
          **Proof of Address is required for following EU Countries:**

          <Columns>
            <div>
              * Croatia
              * Cyprus
              * Czech Republic
              * Estonia
            </div>

            <div>
              * Hungary
              * Latvia
              * Lithuania
              * Malta
            </div>

            <div>
              * Poland
              * Romania
              * Slovakia
              * Slovenia
            </div>
          </Columns>
        </Info>
      </Accordion>

      <Accordion title="🇬🇧 United Kingdom (UK)">
        | **Document Type**     | **Document Name**                                                     |
        | :-------------------- | :-------------------------------------------------------------------- |
        | **Identity Document** | `passport`, `national_id`, `permanent_resident_id`, `driving_license` |
        | **Tax Document**      | `nino`                                                                |

        <Info>
          **Additional Requirements:**

          * Proof of UK address required
        </Info>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Asia-Pacific" icon="flag">
    ### Identity Documents

    <Columns>
      <Card icon="circle-arrow-right">
        * `passport`
      </Card>

      <Card icon="circle-arrow-right">
        * `national_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `permanent_resident_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `driving_license`
      </Card>
    </Columns>

    ### Tax Documents for Asia Pacific Countries

    <Card>
      | **Supported Country** | **Tax Document**                                                              |
      | :-------------------- | :---------------------------------------------------------------------------- |
      | 🇵🇭 Philippines      | `tin` - Tax Identification Number                                             |
      | 🇸🇬 Singapore        | `nric` - National Registration Identity Card, `fin` - Foreign Identity Number |
      | 🇦🇺 Australia        | `tfn` - Tax File Number                                                       |
      | 🇯🇵 Japan            | `my_number` - My Number Card                                                  |
      | 🇰🇷 South Korea      | `rrn` - Resident Registration Number                                          |
      | 🇮🇳 India            | `pan` - Permanent Account Number                                              |
      | 🇲🇾 Malaysia         | `itr` - Income Tax Reference Number                                           |
      | 🇹🇭 Thailand         | `tin` - Tax Identification Number                                             |
    </Card>
  </Accordion>

  <Accordion title="Africa" icon="flag">
    ### Identity Documents

    <Columns>
      <Card icon="circle-arrow-right">
        * `passport`
      </Card>

      <Card icon="circle-arrow-right">
        * `national_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `permanent_resident_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `driving_license`
      </Card>
    </Columns>

    ### Tax Documents for Africa Countries

    <Card>
      | **Supported Country** | **Tax Document**                                                                                              |
      | :-------------------- | :------------------------------------------------------------------------------------------------------------ |
      | 🇳🇬 Nigeria          | `nin` - National Identification Number / `bvn` - Bank Verification Number / `tin` - Tax Identification Number |
      | 🇿🇦 South Africa     | `itr` - Income Tax Reference Number                                                                           |
      | 🇬🇭 Ghana            | `tin` - Tax Identification Number                                                                             |
      | 🇰🇪 Kenya            | *No tax document required*                                                                                    |
      | 🇪🇬 Egypt            | `tin` - Tax Identification Number                                                                             |
      | 🇲🇦 Morocco          | `if` - Identification Fiscal                                                                                  |
    </Card>
  </Accordion>

  <Accordion title="Latin America" icon="flag">
    ### Identity Documents

    <Columns>
      <Card icon="circle-arrow-right">
        * `passport`
      </Card>

      <Card icon="circle-arrow-right">
        * `national_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `permanent_resident_id`
      </Card>

      <Card icon="circle-arrow-right">
        * `driving_license`
      </Card>
    </Columns>

    ### Tax Documents for Latin America Countries

    <Card>
      | **Supported Country** | **Tax Document**                                                                           |
      | :-------------------- | :----------------------------------------------------------------------------------------- |
      | 🇧🇷 Brazil           | `cpf` - Cadastro de Pessoas Físicas                                                        |
      | 🇲🇽 Mexico           | `rfc` - Registro Federal de Contribuyentes / `curp` - Clave Única de Registro de Población |
      | 🇦🇷 Argentina        | `cuil` - Código Único de Identificación Laboral                                            |
      | 🇨🇴 Colombia         | `cc` - Cédula de Ciudadanía                                                                |
      | 🇨🇱 Chile            | `rut` - Registro Único Tributario                                                          |
      | 🇵🇪 Peru             | `ruc` - Registro Único de Contribuyentes                                                   |
    </Card>
  </Accordion>
</AccordionGroup>

***

## Enhanced Due Diligence

For users requiring additional verification or to increase user limits, see [Enhanced Due Diligence](/documentation/developer-platform/users/compliance/enhanced-due-diligence).

***

## Implementation Methods

Carbn Connect offers two approaches for user identity verification:

<AccordionGroup>
  <Accordion title="Direct API Integration (Recommended)" icon="code">
    **API-first approach** for full control over user experience:

    * Build your own KYC collection interface
    * Handle all document collection and validation
    * Manage compliance requirements per region (detailed below)
    * Custom UI/UX design and branding
    * Same processing times as hosted links
    * Average decision time: **under 1 minute** for automated approval
    * Manual reviews: **1-2 business days**

    *Best for organizations that want complete control over their user onboarding experience.*
  </Accordion>

  <Accordion title="Hosted KYC Links" icon="link">
    **Pre-built compliance flow** that handles the complete verification process:

    * Terms of Service acceptance
    * Document collection and verification
    * Automated regulatory compliance checks
    * Faster implementation with minimal development required
    * Same processing times as API integration

    *Ideal for faster time-to-market with proven compliance workflows.*
  </Accordion>
</AccordionGroup>

***

## What's Next?

<CardGroup>
  <Card title="Onboard Your First User" icon="user-plus" href="/documentation/getting-started/onboard-first-user">
    Implement user onboarding with proper KYC handling
  </Card>

  <Card title="User Onboarding Status" icon="users" href="/documentation/developer-platform/users/compliance/user-status">
    Learn about user onboarding status in Carbn Connect
  </Card>
</CardGroup>


# Overview
Source: https://docs.carbn.xyz/documentation/developer-platform/users/compliance/overview

User management and compliance verification

## Users API Overview

The **Users API** and **KYC Links API** allow you to register your end users, enabling seamless and compliant movement of stablecoins or fiat between your users' wallets or bank accounts. Carbn handles all **KYC (Know Your Customer)** and **KYB (Know Your Business)** verification steps, so you have confidence that your users meet all applicable compliance requirements.

***

### Key Concepts

* **Users**: Represent end users of your platform who need identity verification.
* **KYC/KYB**: Mandatory identity and business verification handled by Carbn Connect.
* **User Status**: Verification states (pending, approved, rejected) that determine transaction eligibility.
* **Risk Assessment**: Automated scoring system that evaluates compliance and regulatory requirements.
* **Document Verification**: Secure processing of government-issued IDs and business documents.
* **KYC Links**: Hosted verification flow alternative to direct API integration.

***

## Key Features

<CardGroup>
  <Card title="Automated KYC/KYB" icon="shield-check">
    Streamlined identity verification with automated document processing and verification
  </Card>

  <Card title="Global Compliance" icon="globe">
    Support for compliance requirements across multiple jurisdictions and regulatory frameworks
  </Card>

  <Card title="Risk Management" icon="chart-line">
    Built-in risk assessment and scoring to help manage compliance and regulatory requirements
  </Card>

  <Card title="Document Management" icon="file-text">
    Secure storage and management of user documents with audit trails
  </Card>
</CardGroup>

***

## User Registration

To register a new user, use either the **Users API** or the **KYC Links API**. Upon registration:

* Users must **agree to Carbn Connect's Terms of Service**.
* You must provide **basic identity information** such as:
  * Full name
  * Email address
  * Government-issued identifiers (e.g., SSN for individuals, EIN/TIN for businesses)

Carbn Connect will validate this information to approve the user for transactions. If additional information is needed, Carbn Connect will return precise requirements for completion of the KYC/KYB process.

***

<Note>
  **See Also**: KYC Requirements for a detailed list of required fields and document types.
</Note>

## What's Next?

<CardGroup>
  <Card title="KYC Requirements" icon="shield-check" href="/documentation/developer-platform/users/compliance/kyc-requirements">
    Review KYC requirements for individuals and businesses
  </Card>

  <Card title="Get Setup with Carbn" icon="rocket" href="/documentation/getting-started/setup">
    Start the onboarding process for your region
  </Card>
</CardGroup>


# Rejection Reasons
Source: https://docs.carbn.xyz/documentation/developer-platform/users/compliance/rejection-reasons

Understanding user rejection reasons and how to handle them

If Users API and KYC Links return that the user's KYC status is `rejected`, there are two fields shared with rejection reasons:

* `developer_reason` is meant to be used by developers for **internal purposes only.** This field can contain sensitive information intended for only the developer and is provided to help with troubleshooting potential issues or protecting against potential abuse.
* `reason` can be shared by a developer directly with their users.

| **Develope Reason**                                       | **Reason**                                              |
| :-------------------------------------------------------- | :------------------------------------------------------ |
| ID cannot be verified against third-party databases       | Your information could not be verified                  |
| Inconsistent or incomplete information.                   | Inconsistent or incomplete information.                 |
| Cannot validate user age                                  | Your information could not be verified                  |
| Missing or incomplete barcode on the ID.                  | Cannot validate ID, upload a clear photo of the full ID |
| Inconsistent information in the barcode.                  | Your information could not be verified                  |
| Submission is blurry.                                     | Cannot validate ID - upload photo of ID is clear        |
| Inconsistent ID format                                    | Your information could not be verified                  |
| Compromised ID detected                                   | Your information could not be verified                  |
| ID from disallowed country.                               | Cannot accept provided ID                               |
| Incorrect ID type selected.                               | Incorrect ID type selected.                             |
| Same side submitted as both front and back.               | Same side submitted as both front and back.             |
| Electronic replica detected.                              | Your information could not be verified                  |
| No government ID found in submission.                     | No government ID found in submission.                   |
| ID is expired.                                            | ID is expired.                                          |
| Missing required ID details.                              | Cannot validate ID, upload a clear photo of the full ID |
| Inconsistent details in extraction.                       | Your information could not be verified                  |
| Likely fabrication detected.                              | Your information could not be verified                  |
| Glare detected in the submission.                         | Cannot validate ID, upload a clear photo of the full ID |
| Identity cannot be verified                               | Your information could not be verified                  |
| Inconsistent details with previous submission.            | Your information could not be verified                  |
| Inconsistent details between submissions.                 | Your information could not be verified                  |
| Machine readable zone not detected                        | Cannot validate ID, upload a clear photo of the full ID |
| Inconsistent machine readable zone                        | Cannot validate ID, upload a clear photo of the full ID |
| ID number format inconsistency.                           | Your information could not be verified                  |
| Paper copy detected.                                      | Your information could not be verified                  |
| PO box address detected.                                  | PO box address detected.                                |
| Blurry face portrait.                                     | Cannot validate ID, upload a clear photo of the full ID |
| No face portrait found in the submission.                 | Cannot validate ID, upload a clear photo of the full ID |
| Face portrait matches a public figure.                    | Your information could not be verified                  |
| Not a U.S. REAL ID.                                       | Your information could not be verified                  |
| ID details and face match previous submission.            | Your information could not be verified                  |
| Different faces in ID and selfie.                         | Your information could not be verified                  |
| Tampering detected.                                       | Your information could not be verified                  |
| Submission cannot be processed.                           | Submission cannot be processed.                         |
| Dates on the ID are invalid.                              | Your information could not be verified                  |
| Identity cannot be verified against third-party databases | Your information could not be verified                  |
| Person is deceased.                                       | Your information could not be verified                  |
| Document could not be verified                            | Your information could not be verified                  |
| Unsupported country                                       | Your region is not supported                            |
| No government ID detected                                 | Cannot validate ID, upload a clear photo of the full ID |
| No database check was performed                           | Your information could not be verified                  |
| Prohibited state/province                                 | Your region is not supported                            |
| Prohibited country                                        | Your information could not be verified                  |
| Potential elder abuse                                     | Your information could not be verified                  |
| Potential PEP                                             | Your information could not be verified                  |
| User information could not be verified                    | Your information could not be verified                  |
| Unsupported state/province                                | Your region is not supported                            |
| Missing or invalid proof of address                       | Missing or invalid proof of address                     |


# User Onboarding Status
Source: https://docs.carbn.xyz/documentation/developer-platform/users/compliance/user-status

User onboarding status and how to handle them

## Turnaround response time

The average decision time for KYC is typically less than one minute. If a manual review is required for KYC, the decision may take until next business day.

## User Status Transitions

All KYC flows for individual users begin with users created with basic information. If the provided information is sufficient, they can move directly to `active`, `rejected`, or `under_review`. If something is missing or more information is needed, they move to `incomplete` status.

## User Journey Scenarios

While KYC generally works quickly, there are different paths users can take through the verification process. Understanding these scenarios helps you build better user experiences and handle edge cases appropriately.

<AccordionGroup>
  <Accordion title="Happy Path - Instant Approval" icon="circle-check">
    ```
    created → active
    ```

    **What happens**: User provides complete, accurate information that passes all automated verification checks immediately.
    **Timeline**: Typically under 1 minute
    **User experience**: Seamless onboarding with immediate access
  </Accordion>

  <Accordion title="Additional Information Required" icon="file-search">
    ```
    created → incomplete → active
    ```

    **What happens**: User's basic information is valid, but additional documents are needed (e.g., proof of address, tax documents).
    **Timeline**: Depends on how quickly user provides missing documents
    **User experience**: Clear guidance on what's needed, easy document upload process
  </Accordion>

  <Accordion title="Manual Review Required" icon="user-search">
    ```
    created → under_review → active
    created → under_review → rejected
    ```

    **What happens**: Automated checks flag something that requires human review (e.g., document quality issues, name variations).
    **Timeline**: Up to next business day
    **User experience**: "Under review" messaging with expected timeline
  </Accordion>

  <Accordion title="Immediate Issues Detected" icon="triangle-alert">
    ```
    created → rejected
    ```

    **What happens**: Critical information is incorrect or invalid (e.g., wrong tax ID format, prohibited jurisdiction).
    **Timeline**: Immediate
    **User experience**: Clear error messages with specific guidance on what went wrong
  </Accordion>

  <Accordion title="Complex Scenarios" icon="workflow">
    ```
    created → incomplete → under_review → active
    created → under_review → incomplete → active
    ```

    **What happens**: Multiple verification steps are needed, or additional documents are requested during manual review.
    **Timeline**: Varies based on user responsiveness and review complexity
    **User experience**: Step-by-step progress tracking with clear next actions
  </Accordion>
</AccordionGroup>

### Under Review

In this scenario, the user has provided all required information and documents, but automated verification checks have flagged something that requires human review. This could be due to document quality issues, name variations, or other factors that need manual verification. In this scenario, fetching the user via [Get User Details](/api-reference/user-management/get-user-details) would result in something like this:

```json theme={null}
{
  "id": "user_john_uuid",
  // ...
  "status": "under_review",
  "created_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00",
  "updated_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00"
}
```

You can see that the user's KYC status is `under_review`. This means all required information has been submitted, but a human reviewer needs to manually verify the details. No additional action is required from the user at this point. After the manual review is complete, one of two things will happen:

* Carbn will approve your user, and the KYC status on the user will move to `active`
* Carbn will reject your user, and the KYC status on the user will move to `rejected`.

### Incomplete Status

When a user is in `incomplete` status, it means required information or documents are missing. You can check what's needed by examining the `requirements_due` field in the user object:

```json theme={null}
{
  "id": "user_jane_uuid",
  "status": "incomplete",
  "requirements_due": [
    "proof_of_address",
    "tax_document"
  ],
  "created_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00",
  "updated_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00"
}
```

The `requirements_due` array tells you exactly what documents or information need to be provided. Common requirements include:

* `id_verification` - Government-issued photo ID
* `proof_of_address` - Utility bill, bank statement, or government document
* `tax_document` - Tax identification document specific to the user's country
* `source_of_funds` - Documentation proving origin of funds (for Enhanced Due Diligence)

To resolve incomplete status, submit the required documents through the appropriate API endpoints. Once all requirements are satisfied, the user will move to `active`, `rejected`, or `under_review` status.

### Immediate Rejection

Sometimes, your user could immediately move from created to `rejected` and skip `under_review` entirely. The primary reason this happens is when the tax identification number is entered incorrectly. Without a valid tax identification number, Carbn is unable to verify any of the other details you have sent up for your user (birth date, address, name). In this scenario, the user starts off created with basic information, but after attempting to verify submitted information, there was an issue detected with the submission. It is possible to move directly to `rejected` and skip `under_review` entirely. In the `rejected` scenario, fetching the user would result in something like this:

```json theme={null}
{
  "id": "user_123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "johndoe@johndoe.com",
  "type": "individual",
  "status": "rejected",
  "rejection_reasons": [
    {
      "developer_reason": "Missing required ID details.",
      "reason": "Cannot validate ID -- upload a clear photo of the full ID",
      "created_at": "2020-01-02T00:00:00.000Z"
    },
    {
      "developer_reason": "Blurry face portrait.",
      "reason": "Cannot validate ID -- upload a clear photo of the full ID",
      "created_at": "2020-01-02T00:00:00.000Z"
    }
  ],
  "user_id": "user_123"
}
```

You can see that the user's KYC status is `rejected` and that there are two fields shared with rejection reasons:

* `developer_reason` is meant to be used by developers for **internal purposes only.** This field can contain sensitive information intended for only the developer and is provided to help with troubleshooting potential issues or protecting against potential abuse.
* `reason` can be shared by a developer directly with their users.

For reference, see our page on [Rejection Reasons](/documentation/developer-platform/users/compliance/rejection-reasons) for `developer_reason` and `reason` mappings for KYC rejection reasons.


# Configure Webhooks
Source: https://docs.carbn.xyz/documentation/getting-started/configure-webhook

Set up real-time notifications for payment status updates

Carbn webhooks allow you to receive real-time notifications when payment events occur in your Carbn account. This guide covers registering, implementing, and enabling webhooks using Carbn's REST API.

## Prerequisites

* A Carbn account with API access
* Carbn API credentials (API key)
* HTTPS endpoint with valid certificate
* Development environment with your preferred language

***

## Step 1: Create Your Webhook Endpoint

First, create an endpoint on your server to receive webhook notifications.

### Webhook Payload Structure

All webhook payloads follow this structure:

<CodeGroup>
  ```json Response theme={null}
  {
    "status": "PAYMENT_PROCESSED",
    "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c",
    "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"
  }
  ```
</CodeGroup>

### HTTP Headers

When Carbn sends webhook events, your endpoint will receive these headers:

* `Content-Type: application/json`
* `User-Agent: Java/17.0.14`
* `X-Webhook-Event-Id`: Unique identifier for this delivery attempt
* `X-Webhook-Id`: Identifier of the webhook configuration
* `X-Webhook-Signature`: Base64 encoded signature for payload verification

### Example Webhook Handler

<CodeGroup>
  ```javascript Node.js/Express theme={null}
  const express = require('express');
  const crypto = require('crypto');
  const app = express();

  app.use(express.json());

  app.post('/webhooks/carbn', (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const eventId = req.headers['x-webhook-event-id'];
    const webhookId = req.headers['x-webhook-id'];
    const payload = req.body;
    
    // Verify webhook signature (recommended)
    if (!verifySignature(JSON.stringify(payload), signature)) {
      return res.status(401).send('Unauthorized');
    }
    
    // Handle idempotency using event ID
    if (isEventProcessed(eventId)) {
      return res.status(200).send('Already processed');
    }
    
    const { status, txn_id, user_id } = payload;
    
    switch (status) {
      case 'PAYMENT_PROCESSED':
        handlePaymentProcessed(txn_id, user_id);
        break;
      case 'PAYMENT_FAILED':
        handlePaymentFailed(txn_id, user_id);
        break;
      default:
        console.log('Unknown payment status:', status);
    }
    
    // Mark event as processed
    markEventProcessed(eventId);
    res.status(200).send('OK');
  });

  function verifySignature(payload, signature) {
    // Carbn uses RSA signature verification with base64 encoded signature
    // This is a simplified example - implement proper RSA verification
    const publicKey = process.env.CARBN_PUBLIC_KEY;
    
    try {
      const verify = crypto.createVerify('SHA256');
      verify.update(payload);
      const signatureBuffer = Buffer.from(signature, 'base64');
      return verify.verify(publicKey, signatureBuffer);
    } catch (error) {
      console.error('Signature verification failed:', error);
      return false;
    }
  }

  function handlePaymentProcessed(txnId, userId) {
    console.log(`Payment ${txnId} processed for user ${userId}`);
    // Update your database, notify user, etc.
  }

  function handlePaymentFailed(txnId, userId) {
    console.log(`Payment ${txnId} failed for user ${userId}`);
    // Handle payment failure, notify user, etc.
  }
  ```

  ```python Python/Flask theme={null}
  from flask import Flask, request, jsonify
  import base64
  import json
  from cryptography.hazmat.primitives import hashes
  from cryptography.hazmat.primitives.asymmetric import padding
  from cryptography.hazmat.primitives import serialization

  app = Flask(__name__)
  processed_events = set()

  @app.route('/webhooks/carbn', methods=['POST'])
  def handle_webhook():
      signature = request.headers.get('X-Webhook-Signature')
      event_id = request.headers.get('X-Webhook-Event-Id')
      webhook_id = request.headers.get('X-Webhook-Id')
      
      payload = request.get_data()
      
      # Verify webhook signature (recommended)
      if not verify_signature(payload, signature):
          return jsonify({'error': 'Unauthorized'}), 401
      
      # Handle idempotency
      if event_id in processed_events:
          return jsonify({'status': 'already processed'}), 200
      
      data = request.json
      status = data.get('status')
      txn_id = data.get('txn_id')
      user_id = data.get('user_id')
      
      if status == 'PAYMENT_PROCESSED':
          handle_payment_processed(txn_id, user_id)
      elif status == 'PAYMENT_FAILED':
          handle_payment_failed(txn_id, user_id)
      else:
          print(f'Unknown payment status: {status}')
      
      # Mark event as processed
      processed_events.add(event_id)
      return jsonify({'status': 'success'}), 200

  def verify_signature(payload, signature):
      try:
          # Load your Carbn public key
          public_key_pem = os.environ['CARBN_PUBLIC_KEY']
          public_key = serialization.load_pem_public_key(public_key_pem.encode())
          
          # Decode the base64 signature
          signature_bytes = base64.b64decode(signature)
          
          # Verify the signature
          public_key.verify(
              signature_bytes,
              payload,
              padding.PKCS1v15(),
              hashes.SHA256()
          )
          return True
      except Exception as e:
          print(f'Signature verification failed: {e}')
          return False

  def handle_payment_processed(txn_id, user_id):
      print(f"Payment {txn_id} processed for user {user_id}")
      # Update your database, notify user, etc.

  def handle_payment_failed(txn_id, user_id):
      print(f"Payment {txn_id} failed for user {user_id}")
      # Handle payment failure, notify user, etc.
  ```
</CodeGroup>

***

## Step 2: Register Your Webhook

Once your endpoint is ready, register it with Carbn. You must specify both `url` and `event_category`. **Important:** Webhooks are created with `status: "disabled"` by default and must be enabled separately.

### Webhook event categories

Choose one event category per webhook. Each webhook receives only events for its category:

| Event category               | Description                                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| `ONRAMP_TRANSACTION_STATUS`  | Onramp (fiat-to-crypto) transfer status updates (e.g. initiated, funds received, payment processed). |
| `OFFRAMP_TRANSACTION_STATUS` | Offramp (crypto-to-fiat) transfer status updates.                                                    |
| `PAYOUT`                     | Payout status updates for local currency payouts (e.g. INITIATED, PAYOUT\_PROCESSED, FAILED).        |
| `USER_STATUS_UPDATE`         | User KYC and onboarding status changes (e.g. under\_review, active, rejected, incomplete).           |
| `CUSTODY_WALLET_TRANSACTION` | Custody wallet transfer status updates (e.g. initiated, in\_review, completed).                      |

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.carbnconnect.com/onboarding/api/v1/webhooks \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "url": "https://your-app.com/webhooks/carbn",
      "event_category": "ONRAMP_TRANSACTION_STATUS"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/webhooks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      url: "https://your-app.com/webhooks/carbn",
      event_category: "ONRAMP_TRANSACTION_STATUS"
    })
  });

  const webhook = await response.json();
  console.log('Webhook registered:', webhook.id);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
  }

  data = {
      "url": "https://your-app.com/webhooks/carbn",
      "event_category": "ONRAMP_TRANSACTION_STATUS"
  }

  response = requests.post(
      'https://api.carbnconnect.com/onboarding/api/v1/webhooks',
      headers=headers,
      json=data
  )

  webhook = response.json()
  print(f"Webhook registered: {webhook['id']}")
  ```
</CodeGroup>

**Response:**

<CodeGroup>
  ```json Response theme={null}
  {
    "id": "f79bc473-d45d-4026-86ec-864d4d047905",
    "url": "https://your-app.com/webhooks/carbn",
    "status": "disabled",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```
</CodeGroup>

Save the `webhook_id` from the response - you'll need it to enable the webhook.

***

## Step 3: Enable Your Webhook

Before your webhook can receive events, you must enable it using the PUT endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.carbnconnect.com/onboarding/api/v1/webhooks/{webhook_id} \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "url": "https://your-app.com/webhooks/carbn",
      "status": "enabled"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://api.carbnconnect.com/onboarding/api/v1/webhooks/${webhookId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      url: "https://your-app.com/webhooks/carbn",
      status: "enabled"
    })
  });

  const webhook = await response.json();
  console.log('Webhook enabled:', webhook.status);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
  }

  data = {
      "url": "https://your-app.com/webhooks/carbn",
      "status": "enabled"
  }

  response = requests.put(
      f'https://api.carbnconnect.com/onboarding/api/v1/webhooks/{webhook_id}',
      headers=headers,
      json=data
  )

  webhook = response.json()
  print(f"Webhook status: {webhook['status']}")
  ```
</CodeGroup>

***

## Payment Status Events

Carbn webhooks notify you when payment statuses change. The main status values are:

* **`PAYMENT_PROCESSED`** - Payment has been successfully processed
* **`PAYMENT_FAILED`** - Payment processing failed

**Example payload:**

<CodeGroup>
  ```json Response theme={null}
  {
    "status": "PAYMENT_PROCESSED",
    "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c",
    "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"
  }
  ```
</CodeGroup>

***

## What's Next?

<CardGroup>
  <Card title="Webhook Verification" icon="shield-check" href="/documentation/developer-platform/monitoring/webhook-verification">
    Learn how to verify webhook authenticity using RSA signatures
  </Card>
</CardGroup>

Your webhook is now configured to receive real-time payment notifications from Carbn. Next, implement proper signature verification to ensure webhook security.


# Create Your First Payment
Source: https://docs.carbn.xyz/documentation/getting-started/first-payment



This guide walks you through creating your first payment using Carbn's payment infrastructure. Before initiating payments, ensure your users have completed onboarding and have active status.

## Prerequisites

Before you can create payments, you need:

* **Active Users**: Users must have `active` status after successful KYC verification
* **Registered Accounts**: Users need registered bank accounts or wallets
* **API Authentication**: Valid API key with payment permissions

<Info>
  Users with `under_review`, `rejected`, or `incomplete` status cannot initiate payments.
</Info>

***

## Steps to make your first payment:

<Steps>
  <Step title="Register Destination Account">
    Before initiating transfers, users need registered destination account (bank accounts or wallets).

    <AccordionGroup>
      <Accordion title="Register Bank Account" icon="landmark">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --location --request POST 'https://api.carbnconnect.com/payment/api/v1/accounts/register' \
          --header 'Content-Type: application/json' \
          --header 'x-api-key: <api-key>' \
          --data-raw '{
            "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "account_type": "bank_account",
            "account_details": {
              "account_number": "1234567890",
              "routing_number": "021000021",
              "bank_name": "Example Bank",
              "account_holder_name": "John Doe"
            },
            "currency": "USD"
          }'
          ```

          ```javascript JavaScript theme={null}
          const response = await fetch('https://api.carbnconnect.com/payment/api/v1/accounts/register', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
            },
            body: JSON.stringify({
              user_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              account_type: "bank_account",
              account_details: {
                account_number: "1234567890",
                routing_number: "021000021",
                bank_name: "Example Bank",
                account_holder_name: "John Doe"
              },
              currency: "USD"
            })
          });
          ```

          ```python Python theme={null}
          import requests

          headers = {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
          }

          data = {
              "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "account_type": "bank_account",
              "account_details": {
                  "account_number": "1234567890",
                  "routing_number": "021000021",
                  "bank_name": "Example Bank",
                  "account_holder_name": "John Doe"
              },
              "currency": "USD"
          }

          response = requests.post(
              'https://api.carbnconnect.com/payment/api/v1/accounts/register',
              headers=headers,
              json=data
          )
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="Register Wallet" icon="wallet">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --location --request POST 'https://api.carbnconnect.com/payment/api/v1/wallets/register' \
          --header 'Content-Type: application/json' \
          --header 'x-api-key: <api-key>' \
          --data-raw '{
            "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "crypto": "USDC",
              wallet_address: "3BsSG...",
              blockchain: "solana",
            "source_currency": "USD"
          }'
          ```

          ```javascript JavaScript theme={null}
          const response = await fetch('https://api.carbnconnect.com/payment/api/v1/wallets/register', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
            },
            body: JSON.stringify({
              user_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              crypto: "USDC",
              wallet_address: "3BsSG...",
              blockchain: "solana",
              source_currency: "USD"
            })
          });
          ```

          ```python Python theme={null}
          import requests

          headers = {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
          }

          data = {
              "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "crypto": "USDC",
              "wallet_address": "3BsSG...",
              "blockchain": "solana",
              "source_currency": "USD"
          }

          response = requests.post(
              'https://api.carbnconnect.com/payment/api/v1/wallets/register',
              headers=headers,
              json=data
          )
          ```
        </CodeGroup>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Initiate Onramp Transfer">
    Now that you have registered a destination wallet, you can initiate an onramp transfer (fiat to stablecoins). Carbn Connect supports multiple methods for onramp transfers:

    <AccordionGroup>
      <Accordion title="Open Banking Transfer" icon="arrow-left-right">
        Open Banking provides better visibility and user experience. The deposit links guide users through the payment flow without leaving your application, giving you full control over the user journey.

        <Info>
          **Regional Availability**: Open Banking is currently available for onramp transfers in **US**, **EU**, and **UK**.
        </Info>

        <CodeGroup>
          ```bash cURL theme={null}
          curl --location --request POST 'https://api.carbnconnect.com/payment/api/v1/transfers/onramp' \
          --header 'Content-Type: application/json' \
          --header 'x-api-key: <api-key>' \
          --data-raw '{
            "user_id": "0abad22b-53d3-4473-b1ee-283f4b32e3ad",
            "wallet_id": "34e9819d-2f1c-40a5-9404-a1be8fe34227",
            "open_banking": {
              "amount": 3,
              "redirect_url": "https://www.yourapp.com/payment-success",
              "is_mobile_app": false,
              "country_codes": ["SWE"]
            }
          }'
          ```

          ```javascript JavaScript theme={null}
          const response = await fetch('https://api.carbnconnect.com/payment/api/v1/transfers/onramp', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
            },
            body: JSON.stringify({
              user_id: "0abad22b-53d3-4473-b1ee-283f4b32e3ad",
              wallet_id: "34e9819d-2f1c-40a5-9404-a1be8fe34227",
              open_banking: {
                amount: 3,
                redirect_url: "https://www.yourapp.com/payment-success",
                is_mobile_app: false,
                country_codes: ["SWE"]  // Optional: filter banks by country codes
              }
            })
          });
          ```

          ```python Python theme={null}
          import requests

          headers = {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
          }

          data = {
              "user_id": "0abad22b-53d3-4473-b1ee-283f4b32e3ad",
              "wallet_id": "34e9819d-2f1c-40a5-9404-a1be8fe34227",
              "open_banking": {
                  "amount": 3,
                  "redirect_url": "https://www.yourapp.com/payment-success",
                  "is_mobile_app": False,
                  "country_codes": ["SWE"]  # Optional: filter banks by country codes
              }
          }

          response = requests.post(
              'https://api.carbnconnect.com/payment/api/v1/transfers/onramp',
              headers=headers,
              json=data
          )
          ```
        </CodeGroup>

        <Note>
          **Country Codes Filtering**: The `country_codes` parameter is optional. When not provided, all supported bank countries for the user are available. When provided as an array of ISO 3166-1 alpha-3 country codes (e.g., `["SWE", "NOR"]`), only banks from the specified countries will be shown in the payment flow.
        </Note>

        <CodeGroup>
          ```json Response theme={null}
          {
            "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
            "source_currency": "eur",
            "open_banking": {
              "deposit_link": "https://secure.plaid.com/hl/lpps56nr6p98sn9r89341n78s8834q672q",
              "payment_id": "payment-id-production-2308307c-0d61-46d3-9225-50d48f607e36",
              "link_token": "link-production-cf01ae1c-43fa-4e34-896a-23f3389d127d"
            },
            "v_bank": null
          }
          ```
        </CodeGroup>

        <Note>
          **Open Banking Benefits:**

          * **Better Visibility**: Full payment tracking and monitoring throughout the process
          * **Enhanced UX**: Users never leave your application during payment flow
          * **Real-time Updates**: Immediate payment confirmation and status updates
          * **Amount Control**: Exact amount validation and processing
          * **Seamless Integration**: Embed payment flow directly in your app
          * **Lower Fees**: Reduced processing costs compared to traditional methods
        </Note>
      </Accordion>

      <Accordion title="Virtual Account Transfer" icon="wallet-cards">
        Virtual Account method serves as a fallback option or for payment methods not supported by Open Banking. It generates unique bank account details that users can transfer money to from any bank. However, it provides limited visibility - you can only monitor once funds are deposited, with no tracking of when users initiate payments or control over transfer amounts.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --location --request POST 'https://api.carbnconnect.com/payment/api/v1/transfers/onramp' \
          --header 'Content-Type: application/json' \
          --header 'x-api-key: <api-key>' \
          --data-raw '{
            "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "wallet_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }'
          ```

          ```javascript JavaScript theme={null}
          const response = await fetch('https://api.carbnconnect.com/payment/api/v1/transfers/onramp', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
            },
            body: JSON.stringify({
              user_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              wallet_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            })
          });

          const data = await response.json();
          console.log('Virtual Account Details:', data.v_bank);
          ```

          ```python Python theme={null}
          import requests

          headers = {
              'Content-Type': 'application/json',
              'x-api-key': '<api-key>'
          }

          data = {
              "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
              "wallet_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }

          response = requests.post(
              'https://api.carbnconnect.com/payment/api/v1/transfers/onramp',
              headers=headers,
              json=data
          )

          result = response.json()
          print('Virtual Account Details:', result['v_bank'])
          ```
        </CodeGroup>

        <CodeGroup>
          ```json Response theme={null}
          {
            "transaction_id": null,
            "source_currency": "eur",
            "open_banking": null,
            "v_bank": {
              "bic": "MODRIE22XXX",
              "iban": "IE44MODR99035511728566",
              "bank_name": "Modulr Finance, Ireland Branch",
              "payment_rail": "sepa"
            }
          }
          ```
        </CodeGroup>

        <Warning>
          **Virtual Account Limitations:**

          * **Limited Visibility**: No tracking until funds arrive - you only know when money lands
          * **No Amount Control**: Users can send any amount, not necessarily what was requested
          * **Payment Uncertainty**: No way to know if/when users actually make the transfer
          * **Delayed Monitoring**: Can only monitor after funds are deposited, not during transfer
        </Warning>

        <Info>
          **When to Use Virtual Accounts:**

          * As a fallback when Open Banking is not available
          * For payment methods not supported by Open Banking
          * When users prefer traditional bank transfers
          * For regions outside US/EU/UK where Open Banking isn't available
        </Info>
      </Accordion>

      <Accordion title="QR Payin (PHP)" icon="qr-code">
        QR Payin is available exclusively for PHP (Philippine Peso) transactions. This method generates a QR code that users can scan with their mobile banking app to complete the payment. The QR code has an expiration time and must be used before it expires.

        <Info>
          **Regional Availability**: QR Payin is currently available only for **PHP** currency transactions.

          **Minimum Amount**: The minimum transfer amount for QR Payin is **400 PHP**.
        </Info>

        <CodeGroup>
          ```bash cURL theme={null}
          curl --location --request POST 'https://api.carbnconnect.com/payment/api/v1/transfers/onramp' \
          --header 'Content-Type: application/json' \
          --header 'x-api-key: <api-key>' \
          --data-raw '{
            "user_id": "b8aacdf0-876b-43c1-bbe1-2f2465bbed86",
            "wallet_id": "9a7dc4df-c6a6-4de9-871f-83361b821c29",
            "qr_payin": {
              "amount": 400
            }
          }'
          ```
        </CodeGroup>

        <CodeGroup>
          ```json Response theme={null}
          {
            "transaction_id": "76e12d55-1a25-457e-9e97-0495162de555",
            "source_currency": "PHP",
            "qr_payin": {
              "qr_code": "00020101021228600011ph.ppmi.p2m0111DCPHPHM1XXX03192147235668383093866050301152044814530360854034005802PH5904test6015MAHAGUN MORPHEU62380011ph.ppmi.p2m0519198581120859644569663048038",
              "expiry_time": "2026-02-10T07:13:58.621Z"
            }
          }
          ```
        </CodeGroup>

        <Note>
          **QR Payin Benefits:**

          * **Convenient**: Users can pay by scanning QR code with their mobile banking app
          * **Fast Processing**: Payments are processed quickly once scanned
          * **Mobile-Friendly**: Ideal for mobile-first payment flows
          * **Secure**: Uses standard QR payment protocols
        </Note>

        <Warning>
          **Important**: The QR code has an expiration time. Users must complete the payment before the `expiry_time`. After expiration, a new QR code must be generated.
        </Warning>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

***

## What's Next?

<CardGroup>
  <Card title="Monitor Transfer Status" icon="chart-line" href="/documentation/developer-platform/monitoring/transfer-status">
    Track transfer states and understand the complete payment lifecycle
  </Card>

  <Card title="Configure Webhook" icon="webhook" href="/documentation/getting-started/configure-webhook">
    Set up real-time notifications for payment status updates
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Supported Payment Methods" icon="route" href="/documentation/network/supported-payment-methods">
    Explore supported payment methods, currencies, and assets
  </Card>
</CardGroup>

## Getting Help

<Columns>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz">
    When contacting support, please include:
    <Check>**Transaction ID** of the payment</Check>
    <Check>**Wallet ID** If transfer ID not available</Check>
    <Check>**Transfer type** (FX, on-ramp, off-ramp)</Check>
    <Check>**Error messages** or **status codes** </Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>


# Onboard Your First User
Source: https://docs.carbn.xyz/documentation/getting-started/onboard-first-user

Ready to onboard and verify your first user

This guide walks you through Carbn's two-step user onboarding process: first generating user consent, then creating the verified user profile.

### Understanding User Types

Carbn supports two primary user types:

* **Individual Users**: Personal accounts requiring identity verification and consent
* **Business Users**: Corporate accounts requiring business verification and beneficial ownership details

***

## Step-by-Step Onboarding

<Steps>
  <Step title="Generate User Consent">
    Before creating a user, you must first generate a consent record. This captures the user's acceptance of terms and conditions and generates a consent ID that's required for user creation.

    ### Why Consent is Required

    User consent is a critical compliance requirement that:

    * **Legal Protection**: Establishes clear user agreement to terms of service
    * **Regulatory Compliance**: Meets KYC/AML requirements for financial services
    * **Audit Trail**: Creates verifiable record of user consent with timestamps
    * **Risk Management**: Ensures users understand their obligations and rights

    ### Requirements for Consent

    * User must actively accept current terms and conditions
    * Timestamp must be recorded at time of acceptance
    * Consent must be obtained before any user data processing

    <Note>
      The user must be shown a clear message where they consent to accept the terms and conditions during onborading.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location --request POST 'https://api.carbnconnect.com/onboarding/api/v1/tnc' \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: <api-key>' \
      --data-raw '{
        "tnc_data": {
          "tnc_accepted": true,
          "accepted_at": "2024-01-01T12:00:00Z"
        }
      }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/tnc', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': '<api-key>'
        },
        body: JSON.stringify({
          tnc_data: {
            tnc_accepted: true,
            accepted_at: new Date().toISOString()
          }
        })
      });
      ```

      ```python Python theme={null}
      import requests
      from datetime import datetime

      headers = {
          'Content-Type': 'application/json',
          'x-api-key': '<api-key>'
      }

      data = {
          "tnc_data": {
              "tnc_accepted": True,
              "accepted_at": datetime.utcnow().isoformat() + "Z"
          }
      }

      response = requests.post(
          'https://api.carbnconnect.com/onboarding/api/v1/tnc',
          headers=headers,
          json=data
      )
      ```
    </CodeGroup>

    <CodeGroup>
      ```json Response theme={null}
      "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ```
    </CodeGroup>

    The response is a unique consent ID (UUID) that you'll use in the next step. Store this securely as it's required for user creation.

    ### Importance of Consent

    * **Required Parameter**: The consent ID is mandatory for all user creation requests
    * **Compliance Link**: Connects user profiles to their consent records
    * **Audit Trail**: Enables tracking of consent to user relationship
    * **Legal Requirement**: Proves user agreed to terms before account creation
  </Step>

  <Step title="Create User Profile">
    Now create the user profile using the consent ID from the previous step. This establishes the user's identity within the Carbn network and links them to their consent record.

    ### Understanding Document Types

    The user creation request includes two distinct document categories:

    * **Identity Documents** (`identity` object): Primary identification documents like national ID, passport, or driver's license that prove the user's identity
    * **Supporting Documents** (`documents` array): Additional documents that support the user's profile, such as proof of address, tax documents, or source of funds verification

    <Note>
      Make sure to use the `consent_id` from previous step in your request.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location --request POST 'https://api.carbnconnect.com/onboarding/api/v1/users' \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: <api-key>' \
      --header 'Idempotency-Key: <generate-a-uuid>' \
      --data-raw '{
        "first_name": "John",
        "last_name": "Doe",
        "email_address": "john.doe@example.com",
        "phone_number": "+1234567890",
        "user_type": "individual",
        "date_of_birth": "1990-01-01",
        "consent_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "metadata": "{}",
        "sharing_consent": true,
        "identity": {
          "identity_country_code": "DEU",
          "identity_number": "XXXXXXXXXXXX",
          "identity_document_name": "permanent_residency_id",
          "identity_document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
          "identity_document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
        },
        "documents": [
          {
            "name": "steuer_id",
            "type": "tax_document",
            "issuing_country": "DEU",
            "document_number": "<string>",
            "document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
            "document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
          }
        ],
        "address": {
          "line1": "123 Main Street",
          "city": "City Name",
          "sub_division": "ST",
          "country": "DEU",
          "postal_code": "12345"
        }
      }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/users', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': '<api-key>',
          'Idempotency-Key': '<generate-a-uuid>'
        },
        body: JSON.stringify({
          first_name: "John",
          last_name: "Doe",
          email_address: "john.doe@example.com",
          phone_number: "+1234567890",
          user_type: "individual",
          date_of_birth: "1990-01-01",
          consent_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // From Step 1
          metadata: "{}",
          sharing_consent: true,
          identity: {
            identity_country_code: "DEU",
            identity_number: "XXXXXXXXXXXX",
            identity_document_name: "permanent_residency_id",
            identity_document_front: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
            identity_document_back: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
          },
          documents: [
            {
              name: "steuer_id",
              type: "tax_document",
              issuing_country: "DEU",
              document_number: "<string>",
              document_front: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
              document_back: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
            }
          ],
          address: {
            line1: "123 Main Street",
            city: "City Name",
            sub_division: "ST",
            country: "DEU",
            postal_code: "12345"
          }
        })
      });
      ```

      ```python Python theme={null}
      import requests

      headers = {
          'Content-Type': 'application/json',
          'x-api-key': '<api-key>',
          'Idempotency-Key': '<generate-a-uuid>'
      }

      data = {
          "first_name": "John",
          "last_name": "Doe",
          "email_address": "john.doe@example.com",
          "phone_number": "+1234567890",
          "user_type": "individual",
          "date_of_birth": "1990-01-01",
          "consent_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",  # From Step 1
          "metadata": "{}",
          "sharing_consent": True,
          "identity": {
              "identity_country_code": "DEU",
              "identity_number": "XXXXXXXXXXXX",
              "identity_document_name": "permanent_residency_id",
              "identity_document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
              "identity_document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
          },
          "documents": [
              {
                  "name": "steuer_id",
                  "type": "tax_document",
                  "issuing_country": "DEU",
                  "document_number": "<string>",
                  "document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
                  "document_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
              }
          ],
          "address": {
              "line1": "123 Main Street",
              "city": "City Name",
              "sub_division": "ST",
              "country": "DEU",
              "postal_code": "12345"
          }
      }

      response = requests.post(
          'https://api.carbnconnect.com/onboarding/api/v1/users',
          headers=headers,
          json=data
      )
      ```
    </CodeGroup>

    <CodeGroup>
      ```json Response theme={null}
      {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "under_review",
        "documents": [
          {
            "name": "national_id",
            "type": "identity_front"
          },
          {
            "name": "national_id", 
            "type": "identity_back"
          },
          {
            "name": "steuer_id",
            "type": "tax_document"
          }
        ],
        "first_name": "John",
        "last_name": "Doe",
        "email_address": "john.doe@example.com",
        "phone_number": "+1234567890",
        "date_of_birth": "1990-01-01",
        "address": {
          "line1": "123 Main Street",
          "city": "City Name",
          "sub_division": "ST",
          "country": "DEU",
          "postal_code": "12345"
        },
        "rejection_reasons": null,
        "requirements": null
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## Checking User Status

After creating a user, you can retrieve their current status and details using the GET user endpoint. This endpoint returns the exact same response format as the create and update user endpoints.

<CodeGroup>
  ```bash Get User Details theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}' \
  --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://api.carbnconnect.com/onboarding/api/v1/users/${userId}`, {
    method: 'GET',
    headers: {
      'x-api-key': '<api-key>'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'x-api-key': '<api-key>'
  }

  response = requests.get(
      f'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}',
      headers=headers
  )
  ```
</CodeGroup>

### Understanding User Status Values

The response will include a `status` field that indicates the current state of the user's verification:

<CodeGroup>
  ```json Active User theme={null}
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "active",
    "documents": [
      {
        "name": "national_id",
        "type": "identity_front"
      },
      {
        "name": "national_id", 
        "type": "identity_back"
      },
      {
        "name": "steuer_id",
        "type": "tax_document"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1234567890",
    "date_of_birth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "city": "City Name",
      "sub_division": "ST",
      "country": "DEU",
      "postal_code": "12345"
    },
    "rejection_reasons": null,
    "requirements": null
  }
  ```

  ```json Under Review theme={null}
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "under_review",
    "documents": [
      {
        "name": "national_id",
        "type": "identity_front"
      },
      {
        "name": "national_id", 
        "type": "identity_back"
      },
      {
        "name": "steuer_id",
        "type": "tax_document"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1234567890",
    "date_of_birth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "city": "City Name",
      "sub_division": "ST",
      "country": "DEU",
      "postal_code": "12345"
    },
    "rejection_reasons": null,
    "requirements": null
  }
  ```

  ```json Rejected User theme={null}
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "rejected",
    "documents": [
      {
        "name": "national_id",
        "type": "identity_front"
      },
      {
        "name": "national_id", 
        "type": "identity_back"
      },
      {
        "name": "steuer_id",
        "type": "tax_document"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1234567890",
    "date_of_birth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "city": "City Name",
      "sub_division": "ST",
      "country": "DEU",
      "postal_code": "12345"
    },
    "rejection_reasons": [
      {
        "reason": "Your information could not be verified",
        "created_at": "2025-09-09T11:46:22.037Z",
        "developer_reason": "ID cannot be verified against third-party databases"
      },
      {
        "reason": "Cannot validate ID, upload a clear photo of the full ID",
        "created_at": "2025-09-09T11:47:15.142Z", 
        "developer_reason": "Missing or incomplete barcode on the ID."
      }
    ],
    "requirements": null
  }
  ```

  ```json Incomplete User theme={null}
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "incomplete",
    "documents": [
      {
        "name": "national_id",
        "type": "identity_front"
      },
      {
        "name": "national_id", 
        "type": "identity_back"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1234567890",
    "date_of_birth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "city": "City Name",
      "sub_division": "ST",
      "country": "DEU",
      "postal_code": "12345"
    },
    "rejection_reasons": null,
    "requirements": ["tax_identification_number"]
  }
  ```
</CodeGroup>

### Status Explanations

<AccordionGroup>
  <Accordion title="active" icon="circle-check">
    User has passed verification and can begin transacting. All required documents have been approved and the user is ready to use all platform features.

    **Key Characteristics:**

    * All KYC checks completed successfully
    * User can initiate transactions
  </Accordion>

  <Accordion title="under_review" icon="clock">
    Verification is in progress. Our compliance team is reviewing the submitted documents. This typically takes 2-5 minutes for automated approval.

    **Key Characteristics:**

    * Initial status when user is created
    * Documents are being processed
    * Automated checks in progress
    * User should wait for status update
  </Accordion>

  <Accordion title="rejected" icon="circle-x">
    Verification failed due to document or data issues. The `rejection_reasons` array contains detailed rejection objects with user-safe messages, timestamps, and internal developer reasons.

    **Key Characteristics:**

    * KYC verification failed
    * `rejection_reasons` array populated with detailed objects
    * Each rejection includes `reason`, `created_at`, and `developer_reason`
    * User needs to resubmit with corrections

    <Warning>
      Only share the `reason` field with end users. The `developer_reason` may contain sensitive information.
    </Warning>
  </Accordion>

  <Accordion title="incomplete" icon="circle-alert">
    Missing required information or documents. The `requirements` field lists what's needed to complete the user profile.

    **Key Characteristics:**

    * User profile is missing required data
    * `requirements` array shows what's needed
    * User must provide additional information
    * Status will change once requirements are met

    **Next Steps:**

    * Use the PUT `/onboarding/api/v1/users/{user_id}` endpoint to update user details
    * Provide the missing information listed in the `requirements` array
    * Include any additional documents or data needed
  </Accordion>
</AccordionGroup>

***

## Updating User Information

If a user needs to update their information (due to rejection or incomplete status), use the PUT endpoint to modify their details:

<CodeGroup>
  ```bash Update User theme={null}
  curl --location --request PUT 'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data-raw '{
    "identity": {
      "identity_document_front": "data:image/jpeg;base64,NEW_FRONT_IMAGE...",
      "identity_document_back": "data:image/jpeg;base64,NEW_BACK_IMAGE..."
    },
    "documents": [
      {
        "name": "steuer_id",
        "type": "tax_document",
        "issuing_country": "DEU",
        "document_number": "NEW_DOCUMENT_NUMBER",
        "document_front": "data:image/jpeg;base64,NEW_DOC_FRONT...",
        "document_back": "data:image/jpeg;base64,NEW_DOC_BACK..."
      }
    ]
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://api.carbnconnect.com/onboarding/api/v1/users/${userId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
    },
    body: JSON.stringify({
      identity: {
        identity_document_front: "data:image/jpeg;base64,NEW_FRONT_IMAGE...",
        identity_document_back: "data:image/jpeg;base64,NEW_BACK_IMAGE..."
      },
      documents: [
        {
          name: "steuer_id",
          type: "tax_document",
          issuing_country: "DEU",
          document_number: "NEW_DOCUMENT_NUMBER",
          document_front: "data:image/jpeg;base64,NEW_DOC_FRONT...",
          document_back: "data:image/jpeg;base64,NEW_DOC_BACK..."
        }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Content-Type': 'application/json',
      'x-api-key': '<api-key>'
  }

  data = {
      "identity": {
          "identity_document_front": "data:image/jpeg;base64,NEW_FRONT_IMAGE...",
          "identity_document_back": "data:image/jpeg;base64,NEW_BACK_IMAGE..."
      },
      "documents": [
          {
              "name": "steuer_id",
              "type": "tax_document",
              "issuing_country": "DEU",
              "document_number": "NEW_DOCUMENT_NUMBER",
              "document_front": "data:image/jpeg;base64,NEW_DOC_FRONT...",
              "document_back": "data:image/jpeg;base64,NEW_DOC_BACK..."
          }
      ]
  }

  response = requests.put(
      f'https://api.carbnconnect.com/onboarding/api/v1/users/{user_id}',
      headers=headers,
      json=data
  )
  ```
</CodeGroup>

<Info>
  The PUT endpoint accepts the same fields as the POST endpoint, but all fields are optional. Only include the fields you want to update. The response format is identical to the GET and POST endpoints.
</Info>

***

## What's Next?

After successfully onboarding your first user, here are the essential topics to master:

<CardGroup>
  <Card title="Rejection Reasons" icon="circle-x" href="/documentation/developer-platform/users/compliance/rejection-reasons">
    Understand all possible rejection reasons and how to handle them effectively
  </Card>

  <Card title="Enhanced Due Diligence" icon="shield-check" href="/documentation/developer-platform/users/compliance/enhanced-due-diligence">
    Learn about additional verification requirements for high-risk users
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Understanding Compliance" icon="scale" href="/documentation/developer-platform/users/compliance/overview">
    Deep dive into KYC/AML requirements and regulatory compliance
  </Card>

  <Card title="Setup Webhook" icon="webhook" href="/documentation/getting-started/configure-webhook">
    Configure real-time notifications for user status changes and events
  </Card>
</CardGroup>

## Getting Help

<Columns>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz">
    When contacting support, please include:
    <Check>**User ID** from the response</Check>
    <Check>**Endpoint** you were trying to access</Check>
    <Check>**Error** response details available</Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>


# Get Setup with Carbn
Source: https://docs.carbn.xyz/documentation/getting-started/setup

Let’s get you setup and help navigate our APIs

This guide will help you make your first API call to Carbn Connect and understand the core concepts. You'll create a user, complete KYC, and process your first payment.

## Before you begin

<Steps>
  <Step title="Sign up for an account">
    Create your Carbn account at [dashboard.carbnconnect.com](https://dashboard.carbnconnect.com)
  </Step>

  <Step title="Get your API keys">
    Navigate to **API Keys** in the dashboard and create a new sandbox API key
  </Step>
</Steps>

<Danger>
  Safely store your API keys.
</Danger>

Carbn will share your **API key only once**, so make sure to **immediately copy and save the key safely and securely**. Your key is used to authenticate into our APIs and is highly sensitive. If it ever gets compromised, you can immediately revoke key access from our dashboard and generate a new key.

## Next steps

<CardGroup>
  <Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
    Learn about API keys, rate limits, and security best practices
  </Card>

  <Card title="Error Handling Guide" icon="pencil-ruler" href="/api-reference/errors">
    Learn about error codes, troubleshooting, and best practices
  </Card>
</CardGroup>

## Need help?

We're excited to have you build with us! If you have questions, run into issues, or just want to say hi, you can contact us at [support@carbn.xyz](mailto:support@carbn.xyz)


# Introduction
Source: https://docs.carbn.xyz/documentation/home/introduction



# Carbn Connect API

Carbn is a global payments orchestration platform. The API is designed to provide endpoints to onboard users, create and track payment transactions, receive real-time status updates via webhooks, and retrieve invoices and logs for reconciliation.

## What you can build

Carbn Connect is used by:

* **Fintech companies** - Build cross-border payment features with ready-to-use API infrastructure
* **Payment service providers (PSPs)** - Expand corridor coverage through Carbn network
* **Remittance companies** - Process international money transfers with automated routing and compliance
* **Marketplace platforms** - Handle cross-border seller payouts and international transactions

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/documentation/getting-started/setup">
    Get started with Carbn and start building
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/authentication">
    Complete OpenAPI specification with all endpoints and methods
  </Card>
</CardGroup>

## Key components

<CardGroup>
  <Card title="Users" icon="users">
    User and end-user management with onboarding workflows and identity verification
  </Card>

  <Card title="Virtual Accounts" icon="credit-card">
    Multi-currency virtual accounts with unique account and routing numbers for receiving deposits and managing user funds
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Orchestration" icon="workflow">
    Transaction routing engine that selects optimal licensed partners for each payment corridor
  </Card>

  <Card title="Compliance" icon="shield-check">
    Built-in KYC/KYB collection, sanctions screening, and transaction monitoring for regulatory requirements
  </Card>
</CardGroup>

<Card title="Webhooks" icon="webhook">
  Real-time event notifications for transaction status updates, compliance approvals, and system events
</Card>

## Getting Help

We're excited to have you build with us! If you have questions, run into issues, or just want to say hi, you can contact us at [support@carbn.xyz](mailto:support@carbn.xyz)


# Geographic Coverage
Source: https://docs.carbn.xyz/documentation/network/geographic-coverage



Carbn Connect facilitates payments for users across multiple jurisdictions with varying regulatory requirements. This guide outlines our geographic coverage, regional restrictions, and compliance considerations.

### Worldwide Availability

Carbn Connect facilitates payments through licensed partners in **most countries globally**, excluding jurisdictions subject to international sanctions or with restrictive regulations.

<CardGroup>
  <Card title="Primary Markets" icon="star">
    Established Coverage

    United States, European Union, United Kingdom
  </Card>

  <Card title="Extended Coverage" icon="globe">
    Broad Access

    Africa, Latin America, SEA, Middle East
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Compliance First" icon="shield-check">
    Regulatory Standards

    KYC/AML requirements enforced globally
  </Card>
</CardGroup>

<Note>
  **Exclusions**:

  * OFAC sanctioned countries
  * High-risk jurisdictions per FATF guidelines
  * Regions with prohibitive crypto regulations
</Note>

***

## Primary Markets

### United States 🇺🇸

<AccordionGroup>
  <Accordion title="Supported States" icon="map">
    **Available in**: Most US states

    **State Exclusions**:

    * **New York**: Currently not supported due to BitLicense requirements
    * **Alaska**: Regulatory restrictions apply

    **Business Considerations**:
    For business users, we evaluate based on **principal operating address**:

    <Check>**Supported**: Business incorporated in NY but operating primarily from California</Check>
    <Check>**Supported**: California business banking with NY-based financial institution</Check>
    <Danger>**Not Supported**: Business with primary operations in New York</Danger>
    <Danger>**Not Supported**: Business primarily operating from Alaska</Danger>
  </Accordion>

  <Accordion title="Regulatory Framework" icon="gavel">
    **Partner Compliance Requirements**:

    * Licensed partners hold money transmission licenses in applicable states
    * Bank Secrecy Act (BSA) compliance through partners
    * FinCEN reporting requirements handled by partners
    * State-specific regulatory adherence by licensed partners

    **User Types Supported**:

    * Individual consumers (18+ years)
    * Business entities (LLCs, Corporations, Partnerships)
    * Registered financial institutions

    **Enhanced Due Diligence**:

    * Required for transactions above \$10,000
    * Additional verification for high-risk states
    * Ongoing transaction monitoring
  </Accordion>

  <Accordion title="Documentation Requirements" icon="file-text">
    **Individual Users**:

    * Government-issued photo ID
    * Social Security Number verification
    * Proof of address (utility bill, bank statement)

    **Business Users**:

    * Certificate of incorporation
    * EIN (Employer Identification Number)
    * Beneficial ownership information (25%+ ownership)
    * Operating agreement or bylaws
    * Proof of business address
  </Accordion>
</AccordionGroup>

### European Union 🇪🇺

<AccordionGroup>
  <Accordion title="Supported Countries" icon="map">
    **Available in**: All EU member states

    **Special Requirements**:
    Some countries require **proof of address verification**:

    <Columns>
      <div>
        * Croatia
        * Cyprus
        * Czech Republic
        * Estonia
      </div>

      <div>
        * Hungary
        * Latvia
        * Lithuania
        * Malta
      </div>

      <div>
        * Poland
        * Romania
        * Slovakia
        * Slovenia
      </div>
    </Columns>

    <Info>
      Proof of address must be a recent utility bill, bank statement, or government document dated within the last 3 months.
    </Info>
  </Accordion>

  <Accordion title="Regulatory Framework" icon="gavel">
    **EU Compliance Standards**:

    * Markets in Crypto-Assets (MiCA) regulation
    * General Data Protection Regulation (GDPR)
    * Payment Services Directive 2 (PSD2)
    * Anti-Money Laundering Directive (AMLD5)

    **Open Banking Integration**:

    * PSD2 compliant connections
    * Strong Customer Authentication (SCA)
    * SEPA instant payment support
    * CMA9 equivalent standards

    **Data Protection**:

    * GDPR compliant data processing
    * Right to data portability
    * Right to be forgotten
    * Explicit consent requirements
  </Accordion>

  <Accordion title="Documentation Requirements" icon="file-text">
    **Individual Users**:

    * EU national ID or passport
    * Proof of address (required for specific countries)
    * Tax identification number where applicable

    **Business Users**:

    * Certificate of incorporation
    * VAT registration number
    * Beneficial ownership disclosure
    * Articles of association
    * Proof of business address
    * Authorized signatory documentation
  </Accordion>
</AccordionGroup>

### United Kingdom 🇬🇧

<AccordionGroup>
  <Accordion title="Coverage Details" icon="map">
    **Available in**: England, Scotland, Wales, Northern Ireland

    **Partner Regulatory Status**:

    * Licensed partners are Financial Conduct Authority (FCA) regulated
    * Open Banking CMA9 compliance through partners
    * Faster Payments Scheme integration via partners

    **Post-Brexit Considerations**:

    * Independent regulatory framework
    * Enhanced compliance requirements
    * Separate from EU operations
  </Accordion>

  <Accordion title="Regulatory Framework" icon="gavel">
    **UK Compliance Standards**:

    * Financial Services and Markets Act
    * Money Laundering, Terrorist Financing and Transfer of Funds Regulations
    * Open Banking Implementation Entity (OBIE) standards
    * Strong Customer Authentication requirements

    **Partner FCA Authorization**:

    * Licensed partners hold Electronic Money Institution (EMI) permissions
    * Payment Institution (PI) authorization held by partners
    * Consumer credit activities where applicable through partners
  </Accordion>

  <Accordion title="Documentation Requirements" icon="file-text">
    **Individual Users**:

    * UK driving license or passport
    * Proof of UK address
    * National Insurance number

    **Business Users**:

    * Companies House registration
    * VAT registration (if applicable)
    * Beneficial ownership register
    * Memorandum and Articles of Association
    * Proof of business address
    * Director identification
  </Accordion>
</AccordionGroup>

***

## Coverage Map

<AccordionGroup>
  <Accordion title="Europe & North America" icon="map">
    **European Countries**

    <Columns>
      <Card title="🇮🇪">
        **Ireland**\
        EUR

        *Live*
      </Card>

      <Card title="🇫🇷">
        **France**\
        EUR

        *Live*
      </Card>

      <Card title="🇪🇸">
        **Spain**\
        EUR

        *Live*
      </Card>

      <Card title="🇩🇪">
        **Germany**\
        EUR

        *Live*
      </Card>
    </Columns>

    <Columns>
      <Card title="🇳🇱">
        **Netherlands**\
        EUR

        *Live*
      </Card>

      <Card title="🇧🇪">
        **Belgium**\
        EUR

        *Live*
      </Card>

      <Card title="🇫🇮">
        **Finland**\
        EUR

        *Live*
      </Card>

      <Card title="🇩🇰">
        **Denmark**\
        EUR

        *Live*
      </Card>
    </Columns>

    <Columns>
      <Card title="🇸🇪">
        **Sweden**\
        EUR

        *Live*
      </Card>

      <Card title="🇵🇹">
        **Portugal**\
        EUR

        *Live*
      </Card>

      <Card title="🇦🇹">
        **Austria**\
        EUR

        *Live*
      </Card>

      <Card title="🇮🇹">
        **Italy**\
        EUR

        *Live*
      </Card>
    </Columns>

    <Columns>
      <Card title="🇱🇺">
        **Luxembourg**\
        EUR

        *Live*
      </Card>

      <Card title="🇪🇪">
        **Estonia**\
        EUR

        *Live*
      </Card>

      <Card title="🇱🇹">
        **Lithuania**\
        EUR

        *Live*
      </Card>

      <Card title="🇱🇻">
        **Latvia**\
        EUR

        *Live*
      </Card>
    </Columns>

    **North America**

    <Columns>
      <Card title="🇺🇸">
        **United States**\
        USD

        *Live*
      </Card>

      <Card title="🇨🇦">
        **Canada**\
        CAD

        *Coming Soon*
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Africa" icon="globe">
    **West Africa**

    <Columns>
      <Card title="🇬🇭">
        **Ghana**\
        GHS

        *Live*
      </Card>

      <Card title="🇳🇬">
        **Nigeria**\
        NGN

        *Live*
      </Card>

      <Card title="🌍">
        **CFA Franc Zone**\
        XOF

        *Live*
      </Card>
    </Columns>

    **Central Africa**

    <Columns>
      <Card title="🌍">
        **CFA Franc Zone**\
        XAF

        *Live*
      </Card>
    </Columns>

    **East Africa**

    <Columns>
      <Card title="🇰🇪">
        **Kenya**\
        KES

        *Live*
      </Card>

      <Card title="🇹🇿">
        **Tanzania**\
        TZS

        *Live*
      </Card>

      <Card title="🇺🇬">
        **Uganda**\
        UGX

        *Live*
      </Card>

      <Card title="🇷🇼">
        **Rwanda**\
        RWF

        *Live*
      </Card>
    </Columns>

    **Southern Africa**

    <Columns>
      <Card title="🇿🇦">
        **South Africa**\
        ZAR

        *Live*
      </Card>

      <Card title="🇿🇲">
        **Zambia**\
        ZMW

        *Live*
      </Card>

      <Card title="🇧🇼">
        **Botswana**\
        BWP

        *Live*
      </Card>

      <Card title="🇲🇼">
        **Malawi**\
        MWK

        *Live*
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Asia-Pacific" icon="building">
    **Southeast Asia & Asia-Pacific**

    <Columns>
      <Card title="🇵🇭">
        **Philippines**\
        PHP

        *Live*
      </Card>

      <Card title="🇹🇭">
        **Thailand**\
        THB

        *Live*
      </Card>

      <Card title="🇻🇳">
        **Vietnam**\
        VND

        *Live*
      </Card>
    </Columns>

    <Columns>
      <Card title="🇭🇰">
        **Hong Kong**\
        HKD

        *Live*
      </Card>

      <Card title="🇸🇬">
        **Singapore**\
        SGD

        *Live*
      </Card>

      <Card title="🇮🇩">
        **Indonesia**\
        IDR

        *Live*
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Latin America" icon="banknote">
    **Latin America**

    <Columns>
      <Card title="🇦🇷">
        **Argentina**\
        ARS

        *Live*
      </Card>

      <Card title="🇧🇷">
        **Brazil**\
        BRL

        *Live*
      </Card>

      <Card title="🇲🇽">
        **Mexico**\
        MXN

        *Live*
      </Card>
    </Columns>
  </Accordion>
</AccordionGroup>

<Info>
  **Expansion in Progress**: Additional countries across all regions coming soon through new licensed partnerships.
</Info>

<Note>
  **Carbn provides technology orchestration services**. All financial services are delivered through regulated partners in their respective jurisdictions. Carbn itself does not hold financial licenses and does not operate in the flow of funds.
</Note>

***

## What's Next?

<CardGroup>
  <Card title="Supported Payment Methods" icon="coins" href="/documentation/network/supported-payment-methods">
    Explore supported payment methods, currencies, and assets by region
  </Card>

  <Card title="Get Setup with Carbn" icon="rocket" href="/documentation/getting-started/setup">
    Start the onboarding process for your region
  </Card>
</CardGroup>


# Payment Rails & Currency
Source: https://docs.carbn.xyz/documentation/network/supported-payment-methods



Complete reference for supported payment rails, currencies, and collection methods across all Carbn Connect markets. This page provides detailed technical information for each supported region.

***

## Currency and Payment Rails

### United States

<CardGroup>
  <Card title="ACH">
    *1-3 business days*
  </Card>

  <Card title="ACH Now">
    *Same business day*
  </Card>

  <Card title="FedNow">
    *Real-time*
  </Card>
</CardGroup>

<CardGroup>
  <Card title="RTP">
    *Real-time*
  </Card>

  <Card title="Wire">
    *Real-time*
  </Card>

  <Card title="Open Banking" icon="plus">
    *Real-time*
  </Card>
</CardGroup>

***

### European Union

<CardGroup>
  <Card title="SEPA">
    *1 business day*
  </Card>

  <Card title="SEPA Instant">
    *Real-time*
  </Card>

  <Card title="Open Banking" icon="plus">
    *Real-time*
  </Card>
</CardGroup>

***

### United Kingdom

<CardGroup>
  <Card title="FPS">
    *Real-time*
  </Card>

  <Card title="CHAPS">
    *Same business day*
  </Card>

  <Card title="Open Banking" icon="plus">
    *Real-time*
  </Card>
</CardGroup>

***

### Africa

<AccordionGroup>
  <Accordion title="Mobile Money Networks">
    <CardGroup>
      <Card title="MTN Money">
        **Mobile Wallet Network**\
        *Real-time* | Africa
      </Card>

      <Card title="Orange Money">
        **Mobile Wallet Network**\
        *Real-time* | West & Central Africa
      </Card>

      <Card title="M-Pesa">
        **Mobile Payment System**\
        *Real-time* | East Africa
      </Card>

      <Card title="Airtel Money">
        **Mobile Wallet Network**\
        *Real-time* | East & Southern Africa
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Bank Transfer Networks">
    <CardGroup>
      <Card title="Bank Transfers">
        **Traditional Banking**\
        *1-2 business days* | Africa
      </Card>

      <Card title="USSD Banking">
        **Mobile Banking Codes**\
        *Real-time* | Nigeria, Ghana, others
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Regional Wallets">
    <CardGroup>
      <Card title="Vodafone Cash">
        **Mobile Wallet**\
        *Real-time* | Ghana
      </Card>

      <Card title="TNM Mpamba">
        **Mobile Wallet**\
        *Real-time* | Malawi
      </Card>

      <Card title="EFT">
        **E Fund Transfer**\
        *Real-time* | South Africa
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

### Asia-Pacific

<AccordionGroup>
  <Accordion title="Instant Payment Systems">
    <CardGroup>
      <Card title="InstaPay">
        **Instant Payment System**\
        *Real-time* | Philippines
      </Card>

      <Card title="PESONet">
        **Electronic Fund Transfer**\
        *Next business day* | Philippines
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Mobile Wallets">
    <CardGroup>
      <Card title="GCash">
        **Mobile Wallet**\
        *Real-time* | Philippines
      </Card>

      <Card title="PayMaya">
        **Mobile Wallet**\
        *Real-time* | Philippines
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Bank Transfer Networks">
    <CardGroup>
      <Card title="Bank Transfers">
        **Traditional Banking**\
        *1-2 business days* | Thailand, Vietnam, Hong Kong
      </Card>

      <Card title="Bank Transfers">
        **Traditional Banking**\
        *1-2 business days* | Singapore, Indonesia
      </Card>

      <Card title="Local Payment Rails">
        **Regional Systems**\
        *Varies* | Coming Soon
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

### Latin America

<AccordionGroup>
  <Accordion title="Instant Payment Systems">
    <CardGroup>
      <Card title="Pix">
        **Instant Payment System**\
        *Real-time* | Brazil
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Bank Transfer Networks">
    <CardGroup>
      <Card title="Bank Transfers">
        **Traditional Banking**\
        *1-2 business days* | Argentina, Brazil, Mexico
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## Stablecoins and Chains

### Stablecoins

<CardGroup>
  <Card title="USDC">
    *Most widely supported*
  </Card>

  <Card title="USDT">
    *High liquidity*
  </Card>

  <Card title="EURC">
    *Euro-denominated*
  </Card>
</CardGroup>

### Networks

<CardGroup>
  <Card title="Solana">
    *Fast, Cheap, Scalable*
  </Card>

  <Card title="Stellar">
    *Global, Efficient, Interoperable*
  </Card>

  <Card title="Base">
    *Secure, Developer-Friendly, Coinbase-Backed*
  </Card>

  <Card title="Polygon">
    *Low-Cost, Ethereum-Compatible, Fast*
  </Card>
</CardGroup>

***

## What's Next?

<CardGroup>
  <Card title="Create Your First Payment" icon="credit-card" href="/documentation/getting-started/first-payment">
    Start implementing payments with your chosen method
  </Card>
</CardGroup>


# Welcome
Source: https://docs.carbn.xyz/welcome



<div>
  <div>
    <img alt="Background" />

    <img alt="Background" />
  </div>

  <div>
    <h1>Money that moves like data</h1>

    <p>
      Global Payments Infrastruture For Real-Time Money Movement.
    </p>

    <div>
      <a href="/documentation/getting-started/setup">
        <div>
          <img alt="Quickstart" />

          <img alt="Quickstart" />
        </div>

        <h3>Quickstart</h3>

        <span>
          Get setup with Carbn and start building with our step-by-step guide
        </span>
      </a>

      <a href="/api-reference/authentication">
        <div>
          <img alt="API Reference" />

          <img alt="API Reference" />
        </div>

        <h3>API Reference</h3>

        <span>
          Complete OpenAPI specification with all endpoints and methods
        </span>
      </a>

      <a href="/documentation/network/geographic-coverage">
        <div>
          <img alt="Network Coverage" />

          <img alt="Network Coverage" />
        </div>

        <h3>Network & Global Coverage</h3>

        <span>
          Explore our global network of payment rails and supported regions
        </span>
      </a>

      <a href="/documentation/developer-platform/users/compliance/overview">
        <div>
          <img alt="Developer Platform" />

          <img alt="Developer Platform" />
        </div>

        <h3>Developer Platform</h3>

        <span>
          Advanced tools and resources for building with Carbn Connect
        </span>
      </a>
    </div>
  </div>
</div>