# Add Bank Account Source: https://developer.paywint.com/api-reference/bank-accounts/add POST /api/platform/accounts/add-account - Create a new bank account for a specified user. - Link the bank account to the user for future transactions. - Use this endpoint to add account details. # Delete Bank Account Source: https://developer.paywint.com/api-reference/bank-accounts/delete DELETE /api/platform/accounts/delete/{user_id} Removes a bank account record that belongs to the user. This endpoint: - Deletes the specified bank account if it exists - If the deleted account was the default account, the default flag is reassigned to the next most recently created account (if one exists). # Get Bank Account Source: https://developer.paywint.com/api-reference/bank-accounts/get GET /api/platform/accounts/get-account/{account_id} Retrieves bank account details if the account exists and belongs to a verified user. # List Bank Accounts Source: https://developer.paywint.com/api-reference/bank-accounts/list GET /api/platform/accounts/list/{user_id} Retrieves all bank accounts linked to the specified user, ordered by most recently added. # Overview Source: https://developer.paywint.com/api-reference/bank-accounts/overview Add, verify, and manage bank accounts for users. Users can link external bank accounts to send or receive funds through ACH or other bank-based payment methods.\ The Bank Accounts API provides endpoints to **add**, **verify**, **list**, **update**, and **remove** bank accounts. Verification is completed using a **micro-deposit flow**, where two small deposits are sent to the user’s bank account, and the user confirms the amounts. *** ## How Bank Accounts Are Used Bank accounts let users connect their external financial accounts to support a wide range of money movement. You can add accounts, manage defaults, access account details, list all linked accounts, and remove accounts as needed. These accounts can then be used for ACH payments or for adding funds to a user’s Paywint wallet. *** ## Available APIs Create a new bank account and link it to a user. Initiate micro-deposits for verifying bank ownership. Confirm the two deposit amounts to complete verification. Retrieve details of a specific bank account. Get all bank accounts linked to a user. Remove a bank account that belongs to a user. *** ## How Bank Verification Works Bank verification ensures the account belongs to the user before it can be used for ACH payments or transfers.\ The verification flow is completed in three steps: Call [Add Bank Account](/api-reference/bank-accounts/add) with the account number, routing number, bank details, and account type.\ This adds the bank account to the user’s profile. Call [Release Micro-Deposit](/api-reference/bank-accounts/release-micro-deposit) to initiate two small verification deposits to the bank account.\ These amounts will appear on the user’s bank statement within 1–2 business days.\ In Sandbox, the values are always 0.07 and 0.15. After the user checks their bank statement, call [Verify Micro-Deposit](/api-reference/bank-accounts/verify-micro-deposit) with the two deposit values.\ Once verified, the bank account can be used for ACH payments. *** ## Managing Bank Accounts Use [Get Bank Account](/api-reference/bank-accounts/get) to access account type, last 4 digits, routing number, verification status, and metadata. Use [List Bank Accounts](/api-reference/bank-accounts/list) to fetch all accounts linked to a user, ordered by most recently added. Use [Set Default](/api-reference/bank-accounts/set-default) to switch the default account. Use [Delete Bank Account](/api-reference/bank-accounts/delete) to remove an account.\ If the deleted account was default, the next most recent account becomes default automatically. *** ## Verification States Bank accounts move through the following statuses: | Status | Description | | ---------------- | --------------------------------------------------------------- | | **not\_applied** | No verification started yet | | **pending** | Micro-deposits have been released and are awaiting verification | | **applied** | User submitted verification amounts; processing | | **verified** | Verified successfully; bank account can be used for transfers | | **failed** | Verification failed; new micro-deposit release is required | ## Best Practices * Always display the last 4 digits of the bank account number for user confirmation * Encourage users to wait 1–2 business days for real micro-deposits * In Sandbox, verification requires **exactly** `0.07` and `0.15` * Use the default account for ACH and payouts unless overridden per request # Release Micro-Deposit Source: https://developer.paywint.com/api-reference/bank-accounts/release-micro-deposit POST /api/platform/accounts/release-micro-deposit/{user_id} Starts the micro-deposit verification process for a user’s bank account. This endpoint performs the following actions: - Prevents duplicate or overlapping verification attempts - Initiates and releases micro-deposits if the account is eligible - Updates the bank account’s verification status # Set Bank Account To Default Source: https://developer.paywint.com/api-reference/bank-accounts/set-default POST /api/platform/accounts/set-default/{user_id} Set a specific bank account as the default account for a user. This endpoint enables platforms to: - Designate a user's bank account as their default account - Automatically unset any previously set default accounts for the same user - Ensure only one default account exists per user # Verify Micro-Deposit Source: https://developer.paywint.com/api-reference/bank-accounts/verify-micro-deposit POST /api/platform/accounts/verify-micro-deposit/{user_id} Finalizes the micro-deposit verification process for a user’s bank account. This endpoint: - Validates the two micro-deposit amounts to confirm bank account ownership - Ensures the account is currently in `APPLIED` verification status - Updates the account status to `VERIFIED` upon successful confirmation - Logs a user note documenting the verification event **Note:** - In the **sandbox environment**, the two required test deposit amounts are **$0.07** and **$0.15**. These values must be provided exactly in any order. - In **live (production)** environments, actual micro-deposits will be sent to the user’s bank account, and those values must be retrieved from the user’s bank statement and submitted here. # Add Card Source: https://developer.paywint.com/api-reference/cards/add POST /api/platform/card/add/secure-link/{user_id} Returns a short-lived secure link to initiate the Add Card process for a user. This endpoint: - Generates a secure link based on the provided `card_purpose` (PAYMENT or WITHDRAWAL) - The link is valid for a limited time and intended for new card addition only **Usage Notes:** - The link expires after 30 minutes - Open the `secure_link` in a new browser window or iframe immediately after generation - Do not reuse the link or repurpose it for card editing # Delete Card Source: https://developer.paywint.com/api-reference/cards/delete DELETE /api/platform/card/delete/{user_id} Delete a user card associated with the specified card ID. This endpoint: - Validates platform API key and user association - Deletes the specified card # Get Card Source: https://developer.paywint.com/api-reference/cards/get GET /api/platform/card/get-card/{card_id} Retrieves card details if the card exists and belongs to a verified user. **Usage Notes:** Depending on the card's current state, further actions may be required: - `card_images_required`: The cardholder must upload both front and back images before the card can be used for any transactions. - `withdrawal_confirm_required`: A withdrawal setup or confirmation step must be completed before withdrawals are allowed. - `payment_confirm_required`: Additional registration or verification is required before new payments can be made with this card. - `compliance_check_required`: Indicates whether KYC/KYB compliance should be checked before card payments. - `is_limited`: The user has reached their daily payment limit. → Note: When `is_limited` is `true`, no new payments can be made today using this card, but withdrawals are still permitted. If any of the first three flags (`card_images_required`, `withdrawal_confirm_required`, or `payment_confirm_required`) are set to `true`, the card must be updated before it can be fully used.
→ Use the [Update Card Endpoint](/api-reference/cards/update-card) to complete the necessary steps. # List Cards Source: https://developer.paywint.com/api-reference/cards/list GET /api/platform/card/list/{user_id} Retrieve a list of all cards associated with the authenticated user. **Usage Notes:** Each returned card may include one or more status flags that indicate required user actions or usage limitations: - `card_images_required`: The cardholder must upload both front and back images before the card can be used for any transactions. - `withdrawal_confirm_required`: A withdrawal setup or confirmation step must be completed before withdrawals are allowed. - `payment_confirm_required`: Additional registration or verification is required before new payments can be made with this card. - `compliance_check_required`: Indicates whether KYC/KYB compliance should be checked before card payments. - `is_limited`: The user has reached their daily payment limit. → Note: No new payments can be made today using card, but withdrawals are still permitted. If any of the first three flags (`card_images_required`, `withdrawal_confirm_required`, or `payment_confirm_required`) are `true`, the card must be updated before use.
→ Use the [Update Card Endpoint](/api-reference/cards/update-card) to complete the necessary steps. # Overview Source: https://developer.paywint.com/api-reference/cards/overview Link, verify, retrieve, list, and manage user debit and credit cards. Users can link debit or credit cards to their Paywint profile so they can fund payments or receive withdrawals.\ Paywint handles all sensitive card data through secure, time-limited links, ensuring that no card information ever touches your servers. The card flow is straightforward: * **Add Card** — Create a secure link for the user to add a new card * **Update Card** — Only required when Paywint asks the user to complete missing information or verification steps *** ## Card Features You can: * Provide users a secure link to add a card * Allow required updates when Paywint flags missing steps * Retrieve card details and verification requirements * List all cards for a user * Delete a card when needed Cards may be used for: * Funding payments * Receiving withdrawals (when configured for that purpose) *** ## Available APIs Generate a secure link for adding a new card. Generate a secure link only when the user must complete required steps. Retrieve card details and required action flags. Fetch all cards linked to a user. Remove a card from the user’s account. *** ## How the Card Flow Works Call [Add Card](/api-reference/cards/add) to create a secure link for adding a new card.\ The link is valid for 30 minutes and must be opened immediately. The user adds their card on the Paywint-hosted page.\ Sensitive card details never go through your platform. Once completed, the card is ready for payments or withdrawals based on its purpose. *** ## When the User Must Update Their Card The **Update Card** flow is not for general editing.\ A user only needs to update a card when Paywint determines that: * Required card images are missing * Additional verification is needed for withdrawals * Payment confirmation is required before new payments * A security or compliance check requires the user to re-authenticate the card In these cases, **Paywint temporarily restricts the card** until the user completes the update link. Call the update endpoint to generate a secure link, and the user finishes the required step in the Paywint-hosted form. *** ## Card Status Flags When retrieving a card, these flags indicate required user actions: | Flag | Meaning | | --------------------------------- | -------------------------------------------------------------------- | | **card\_images\_required** | User must upload images before the card is usable. | | **withdrawal\_confirm\_required** | Additional setup needed for withdrawal capability. | | **payment\_confirm\_required** | Extra verification required before processing new payments. | | **is\_limited** | User reached their daily spending limit (withdrawals still allowed). | If any of the first three flags are true, direct the user through the **Update Card** flow. *** ## Best Practices * Always open add/update secure links immediately after generation * Do not reuse expired links (valid for 30 minutes) * Use card flags to determine when an update is required * Display only masked card details (e.g., last 4 digits) # Update Card Source: https://developer.paywint.com/api-reference/cards/update POST /api/platform/card/update/secure-link/{user_id} Returns a short-lived secure link to initiate the Update Card process for a user. This endpoint: - Generates a secure link based on the provided `card_purpose` (PAYMENT or WITHDRAWAL) - The link is valid for a limited time and intended for card updation only **Usage Notes:** - The link expires after 30 minutes - Open the `secure_link` in a new browser window or iframe immediately after generation - Do not reuse the link or repurpose it for card editing # Add Check Address Source: https://developer.paywint.com/api-reference/checks/add-address POST /api/platform/check/add-address/{user_id} Create and store a mailing address used for sending physical checks on behalf of a specific user. This endpoint: - Creates a **check mailing address** for the user - Returns the newly created address in a standardized response # Overview Source: https://developer.paywint.com/api-reference/checks/overview Manage mailing addresses and check settings used for sending physical checks. Paywint supports sending physical mailed checks as one of its payment methods.\ Before a check can be issued, each user must have: * A valid **check mailing address**, and * Optional **check configuration settings** such as custom logo or signature. This section provides the APIs needed to manage check-related details for your users. *** ## What This API Covers The Check Management API allows you to: * Create and maintain a user's **check mailing address** * Update address details at any time * Configure check appearance (logo, signature) * Reset branding back to Paywint defaults * Support mailed-check payments created through the Payments API These APIs do **not** send a check directly.\ Checks are delivered through the [Mail Check](/api-reference/payments/mail-check) endpoint inside the [Payments](/api-reference/payments/overview) section. *** ## Available APIs Create a new mailing address used for sending physical checks. Modify an existing check mailing address for the user. Configure check branding, including logo and signature image. *** ## When Check Management Is Used You should manage check settings when: * A user wants payments delivered as physical checks * The mailing address changes * A business wants custom branding (logo or signature) on mailed checks * You want to reset a user's check branding back to the Paywint default These settings ensure every mailed check contains accurate address information and optional branded elements. *** ## Easily manage checks Call [Add Check Address](/api-reference/checks/add-address) to store the recipient address used for mailing checks. Use [Update Check Config](/api-reference/checks/update-config) to include a logo or signature.\ This step is optional—Paywint uses a default design if none is provided. At any time, you may update the user’s details using the corresponding endpoints. When sending a payment using the Payments API with the **Mail Check** method,\ Paywint uses the stored address and configuration to issue the check. *** ## Best Practices * Always keep the user's check address up-to-date before issuing mailed checks * Use publicly accessible HTTPS URLs for logos and signatures * Allow users to preview their check branding inside your application * If branding is optional for your use case, rely on Paywint’s default settings # Update Check Address Source: https://developer.paywint.com/api-reference/checks/update-address PATCH /api/platform/check/update-address/{user_id} Update the existing **check mailing address** for a specific user. This endpoint: - Applies partial or full updates to the saved mailing address - Returns the updated address in a standardized response # Update Check Config Source: https://developer.paywint.com/api-reference/checks/update-config POST /api/platform/check/update-config/{user_id} Update the **check settings** for a specific user, including branding and preferences used when mailing checks. This endpoint: - Requires platform API key authentication - Ensures the `user_id` belongs to the requesting platform - Updates settings such as check **logo**, **signature**, and related preferences - Supports resetting the logo to the system default - Returns the updated check settings in a standardized response # Get KYB Source: https://developer.paywint.com/api-reference/compliance/kyb/get GET /api/platform/kyb/{user_id} This endpoint: - Verifies the platform and user relationship - Retrieves the KYB record associated with the given user ID - Returns detailed KYB data if found, otherwise raises a 404 error # Submit KYB Source: https://developer.paywint.com/api-reference/compliance/kyb/submit POST /api/platform/kyb/submit-kyb/{user_id} Initiates business verification for a specific user. This endpoint allows to: - Submit KYB (Know Your Business) details on behalf of a user - Provide business information and at least two document URLs (`document_1` and `document_2`) - URLs must be valid, public, and direct links to document images (e.g., licenses or business filings) # Submit KYC Source: https://developer.paywint.com/api-reference/compliance/kyc/create-enquiry-link GET /api/platform/persona/platform-user/inquiry/{user_id} Retrieve a verification link to initiate or resume identity verification for a specific user. This endpoint: - Returns a `inquiry_url` if the user’s verification is pending - Indicates `is_kyc_pending = false` if no further action is required **Usage Notes:** - Open the returned URL in a new browser window or embed it in an iframe - Use this only when the user has not completed their verification process # Get KYC Source: https://developer.paywint.com/api-reference/compliance/kyc/get GET /api/platform/users/kyc/{user_id} Retrieve the Know Your Customer (KYC) details for a specific user. This endpoint: - Validates the platform-user relationship - Fetches the KYC record associated with the given user ID - Returns the KYC information if found, otherwise raises a 404 error # Overview Source: https://developer.paywint.com/api-reference/compliance/overview KYC and KYB verification flows for users and businesses on Paywint. Paywint uses industry-standard identity and business verification to ensure secure and compliant financial operations.\ Compliance applies **only to specific payment methods** and **not** to wallet-to-wallet transfers. You can initiate and manage both **KYC (Know Your Customer)** and **KYB (Know Your Business)** through the API. *** ## KYC Verification (Individuals) KYC is handled through Paywint’s integrated **Persona** flow.\ Your platform calls the API to obtain a **verification link**, and the user completes KYC in a hosted or embedded Persona widget. Retrieve a verification link to initiate or resume KYC for a user. Fetch KYC details after verification is completed. *** ## How KYC Works When you call the **Submit KYC** endpoint, Paywint returns: * `inquiry_url` → Persona verification link * `is_kyc_pending` → Whether verification is still needed Open this link in: Embed the Persona identity verification flow directly inside your application using an iFrame.\ This option keeps users fully within your UI while Paywint and Persona handle document capture, identity validation, and compliance processing behind the scenes.
Your backend calls\ [Submit KYC](/api-reference/compliance/kyc/create-enquiry-link)\ to retrieve the inquiry\_url. Load the inquiry\_url in an
\</code>.
      </Step>

      <Step title="User completes verification">
        The user uploads ID documents and completes all required steps directly inside your flow.
      </Step>

      <Step title="Persona completion">
        When the user presses the “Done” button in Persona, Paywint receives a redirect callback.
      </Step>

      <Step title="Paywint sends webhook">
        After verification data is processed, Paywint sends a lifecycle webhook to your server.
      </Step>

      <Step title="Fetch KYC">
        Your server calls [Get KYC](/api-reference/compliance/kyc/get) to retrieve verification details and status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Hosted Page">
    Redirect users to Persona’s secure hosted verification page.\
    This option requires no front-end development and provides the quickest way to start collecting identity information for compliance.

    <Frame>
      <img alt="Embedded checkout form" />
    </Frame>

    <Steps>
      <Step title="Call Submit KYC">
        Your backend requests the <code>inquiry\_url</code> using\
        [Submit KYC](/api-reference/compliance/kyc/create-enquiry-link).
      </Step>

      <Step title="Redirect the user">
        Your front-end redirects the user to the hosted Persona page.
      </Step>

      <Step title="User completes KYC">
        The user finishes verification on Persona’s hosted page.
      </Step>

      <Step title="Redirect callback">
        Persona notifies Paywint when the flow is completed.\
        Paywint then redirects the user to your configured redirect URL.
      </Step>

      <Step title="Webhook notification">
        Paywint sends a compliance webhook to your backend when KYC data is processed.
      </Step>

      <Step title="Fetch updated KYC">
        Your server fetches the user’s updated verification details using [Get KYC](/api-reference/compliance/kyc/get).
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## KYB Verification (Businesses)

KYB verifies business information such as legal entity details, documents, EIN, and formation data.

<CardGroup>
  <Card title="Submit KYB" icon="external-link" href="/api-reference/compliance/kyb/submit">
    Submit business information and mandatory supporting documents.
  </Card>

  <Card title="Get KYB Status" icon="list" href="/api-reference/compliance/kyb/get">
    Retrieve business verification results and document metadata.
  </Card>
</CardGroup>

***

## How KYB Works

Submitting KYB requires:

* Business details (name, address, EIN, entity type, etc.)
* At least **two** publicly accessible document URLs\
  (You can link to your documentation page about document URL requirements)

<Callout type="info">
  Looking for document upload rules?\
  See **[Document Upload Guidelines](/guidelines/url-standards/overview)**
</Callout>

<Steps>
  <Step title="Submit KYB">
    Make call to [Submit KYB](/api-reference/compliance/kyb/submit) with business information and document URLs.
  </Step>

  <Step title="Paywint validates documents">
    Paywint checks required fields and validates submitted URLs.
  </Step>

  <Step title="Verification processing">
    KYB review is completed asynchronously by Paywint and compliance partners.
  </Step>

  <Step title="Webhook delivered">
    Once processing is complete, Paywint sends a webhook notifying you of changes in KYB status.
  </Step>

  <Step title="Retrieve KYB record">
    Your server calls [Get KYB](/api-reference/compliance/kyb/get) to read the latest business verification data.
  </Step>
</Steps>

***

## When Compliance Is Required

| Feature                       | Requires KYC?             | Requires KYB?             |
| ----------------------------- | ------------------------- | ------------------------- |
| Wallet-to-wallet payments     | <Icon icon="x" /> No      | <Icon icon="x" /> No      |
| Adding a bank account         | <Icon icon="x" /> No      | <Icon icon="x" /> No      |
| Wallet-Funding                | <Icon icon="check" /> Yes | <Icon icon="check" /> Yes |
| ACH transfers                 | <Icon icon="check" /> Yes | <Icon icon="check" /> Yes |
| Card payouts                  | <Icon icon="check" /> Yes | <Icon icon="x" /> No      |
| Business account features     | <Icon icon="check" /> Yes | <Icon icon="check" /> Yes |
| High-risk/regulated use cases | <Icon icon="check" /> Yes | <Icon icon="check" /> Yes |

## Webhooks

Paywint sends webhook notifications as KYC or KYB verification progresses.\
These include:

* Verification started
* Data received
* User/business status updated
* Verification completed or requiring additional documents

> Exact event names and payloads are listed in\
> **[Webhook Event Types](/webhooks/event-types)**.

***

## Best Practices

* Always open Persona in a secure frame or new tab.
* Use `Get KYC` and `Get KYB` after receiving webhook notifications.
* Use descriptive business documents and ensure they are publicly accessible URLs.
* Ensure your compliance webhook endpoint is always available.


# Add a Payee Address
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/add-payee-address

POST /api/platform/cross-border/payee/address/{user_id}
Adds a cross-border address for a payee.

Identify the payee by `payee_id` (the payee's user id). Send the payee's name and address fields
(with the country as an ISO2 code). Each field only accepts values within the maximum length allowed
by the payee rules for the destination country — see `GET /cross-border/payee-rules`. Returns the
created cross-border address.



# Add a Payee Bank
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/add-payee-bank

POST /api/platform/cross-border/payee/bank/{user_id}
Adds a cross-border bank account for a payee.

Identify the payee by `payee_id`. Send the bank details — `account_number`, `country` (ISO2),
`bank_acc_type`, `identifier_type`, `identifier_value`, an optional `bank_nick_name` and an optional
`payout_bank_id`. Each field only accepts values within the maximum length allowed by the payee rules
for the destination country — see `GET /cross-border/payee-rules`. Returns the created cross-border bank.



# Create a Cross-Border Payment
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/create-a-cross-border-payment

POST /api/platform/cross-border/create-payment
Creates a cross-border payment from a platform user's wallet to a saved payee bank.

Send:
- `payer_id` (alias `user_id`) — the user funding the payment
- `payee_id` — the payee
- `to_bank_id` — the saved payee bank
- `amount` — the **source amount in USD**, plus `payout_currency`, `invoice_no` and an optional `description`

**Amount limits** (the source `amount` in USD, both inclusive):
- **Minimum amount: `$10 USD`**
- **Maximum amount: `$5,000 USD`**, except:
  - **Pakistan (`payout_currency: PKR`): `$3,500 USD`**

The maximum depends on the destination `payout_currency`. A request below the minimum or above the
applicable maximum is rejected with `AMOUNT_OUT_OF_RANGE`, and the error payload echoes `min_amount`,
`max_amount` (the maximum that applied) and `currency` (USD).

Also rejects with `COUNTRY_NOT_ALLOWED` if the payee country is not enabled for the platform, or
`MISSING_REQUIRED_FIELDS` when a required payee field is missing. Returns the created payment;
progress is delivered via `payment.*` webhooks.



# Delete a Payee Bank
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/delete-payee-bank

DELETE /api/platform/cross-border/payee/bank/{user_id}/{bank_uuid}
Deletes a payee bank account for the given user.

Returns `404` if the bank does not exist for the user.



# Edit a Payee Address
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/edit-a-payee-address

PATCH /api/platform/cross-border/payee/address/{user_id}/{address_id}
Edits a cross-border payee address.

Send only the address fields to change — recipient name, address line, city, state or zipcode. Each
field only accepts values within the maximum length allowed by the payee rules for the destination
country — see `GET /cross-border/payee-rules`. The country cannot be changed (it is fixed when the
address is created). Returns the updated address.



# Get a Payee Address
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/get-a-payee-address

GET /api/platform/cross-border/payee/address/{user_id}/{address_id}
Fetches a single cross-border payee address by its id.

Returns the submitted address fields. Returns `404` if the address does not exist for the user.



# Get Exchange Rates
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/get-exchange-rates

GET /api/platform/cross-border/rates
Returns the current exchange rates for a payout currency.

Each rate provides its `exchange_rate`, base/payout currency and apply time. Use it to quote
the payout amount before creating a payout.



# Get Payee Rules (Mandatory Fields)
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/get-payee-rules

GET /api/platform/cross-border/payee-rules
Returns the payee rules for a destination `country` (ISO2) and payout `currency`.

The response lists the **mandatory** and **optional** payee fields and the amount limits — the
fields you need to collect for the payee.



# List Payee Addresses
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/list-payee-addresses

GET /api/platform/cross-border/payee/addresses/{user_id}
Lists a user's saved cross-border payee addresses.

Filtered to a single payee by `payee_id` (the payee's user id). Each address is returned with its
submitted fields. Returns an empty list when the payee has no cross-border address yet.



# List Payee Banks
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/list-payee-banks

GET /api/platform/cross-border/payee/banks/{user_id}
Lists a user's saved cross-border payee banks.

Filtered to a single payee by `payee_id` (the payee's user id). Each bank is returned with its
stored details. Returns an empty list when the payee has no cross-border bank yet.



# List Payout Banks
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/list-payout-banks

GET /api/platform/cross-border/payout-banks
Returns the list of supported payout banks for cross-border payments. Currently, this endpoint returns
banks for **Pakistan (`PKR`)** and the **UAE (`AED`)**. Use the returned bank `id` as the
`payout_bank_id` in the
[Create a Cross-Border Payment](/api-reference/cross-boarder-payments/create-a-cross-border-payment)
endpoint. The `payout_bank_id` field is required only when the destination country is Pakistan or the UAE.



# Overview
Source: https://developer.paywint.com/api-reference/cross-boarder-payments/overview

Everything you need to send cross-border payments through the Paywint API.

The **Cross-Border Payments API** helps you send international payments for your users.
The flow is simple: check the rules, save the payee details, then create the payment.

***

## How It Works

<Steps>
  <Step title="Check the rules">
    Start with [Get Payee Rules (Mandatory Fields)](/api-reference/cross-boarder-payments/get-payee-rules)
    so you know which fields are required for the payment.
  </Step>

  <Step title="Review bank and rate data">
    Use [List Payout Banks](/api-reference/cross-boarder-payments/list-payout-banks) and
    [Get Exchange Rates](/api-reference/cross-boarder-payments/get-exchange-rates)
    before you submit the payment.
  </Step>

  <Step title="Save the payee details">
    Add the recipient's [Payee Address](/api-reference/cross-boarder-payments/add-payee-address)
    and [Payee Bank](/api-reference/cross-boarder-payments/add-payee-bank).
    You can reuse them for future payments.
  </Step>

  <Step title="Create the payment">
    Submit the transfer with
    [Create a Cross-Border Payment](/api-reference/cross-boarder-payments/create-a-cross-border-payment).
  </Step>
</Steps>

<Info>
  Payee addresses and banks are stored **per user** (`user_id`). Set them up once and reuse them for
  every subsequent payout to that recipient.
</Info>

***

## Reference Data & Rates

<CardGroup>
  <Card title="List Payout Banks" icon="building-columns" href="/api-reference/cross-boarder-payments/list-payout-banks">
    List the available payout banks for supported destinations.
  </Card>

  <Card title="Get Exchange Rates" icon="dollar-sign" href="/api-reference/cross-boarder-payments/get-exchange-rates">
    View the exchange rate information used when creating a payout.
  </Card>

  <Card title="Get Payee Rules (Mandatory Fields)" icon="list-check" href="/api-reference/cross-boarder-payments/get-payee-rules">
    Inspect the payee-specific mandatory fields required before creating a payout.
  </Card>
</CardGroup>

***

## Payee Setup

### Addresses

<CardGroup>
  <Card title="Add a Payee Address" icon="plus" href="/api-reference/cross-boarder-payments/add-payee-address">
    Save a payee address for a user before bank setup or payout creation.
  </Card>

  <Card title="Get a Payee Address" icon="receipt" href="/api-reference/cross-boarder-payments/get-a-payee-address">
    Retrieve a specific saved payee address by user and address ID.
  </Card>

  <Card title="Edit a Payee Address" icon="pencil" href="/api-reference/cross-boarder-payments/edit-a-payee-address">
    Update a saved payee address for a specific user.
  </Card>

  <Card title="List Payee Addresses" icon="list" href="/api-reference/cross-boarder-payments/list-payee-addresses">
    Retrieve all saved payee addresses for a specific user.
  </Card>
</CardGroup>

### Bank Accounts

<CardGroup>
  <Card title="Add a Payee Bank" icon="plus" href="/api-reference/cross-boarder-payments/add-payee-bank">
    Save a payee bank account for cross-border payouts.
  </Card>

  <Card title="List Payee Banks" icon="list" href="/api-reference/cross-boarder-payments/list-payee-banks">
    Retrieve all saved payee bank accounts for a specific user.
  </Card>

  <Card title="Delete a Payee Bank" icon="trash" href="/api-reference/cross-boarder-payments/delete-payee-bank">
    Remove a saved payee bank account for a user.
  </Card>
</CardGroup>

***

## Payments

<CardGroup>
  <Card title="Create a Cross-Border Payment" icon="paper-plane" href="/api-reference/cross-boarder-payments/create-a-cross-border-payment">
    Create and submit a new cross-border payment for a user's payee.
  </Card>
</CardGroup>

***

## Best Practices

* Always read **[Payee Rules](/api-reference/cross-boarder-payments/get-payee-rules)** for the target
  corridor before collecting payee details — required fields vary by country and bank.
* Fetch **[Exchange Rates](/api-reference/cross-boarder-payments/get-exchange-rates)** close to payout
  time so quoted amounts reflect current rates.
* Reuse saved payee **addresses** and **banks** instead of recreating them for every payout.
* Use webhooks or your own downstream reconciliation flow rather than assuming success on creation.


# Add Payee Address
Source: https://developer.paywint.com/api-reference/payees/addresses/add

POST /api/platform/address/create-payee-address/{user_id}
Creates a new address for an existing payee contact.

This endpoint will:
- Verify the payee exists and belongs to the specified user
- Validate the address information and format
- Check that the payee hasn't exceeded the maximum of 5 addresses
- Create and store the new address for future check payments

Each payee can have up to 20 different addresses to support multiple locations
or address changes. These addresses can be used when sending physical check payments.



# Delete Payee Address
Source: https://developer.paywint.com/api-reference/payees/addresses/delete

DELETE /api/platform/address/delete-payee-address/{user_id}
Removes a saved address from an existing payee contact.

This endpoint will:
- Ensure the address belongs to that payee
- Delete the address from the payee’s saved addresses



# List Payee Address
Source: https://developer.paywint.com/api-reference/payees/addresses/list

POST /api/platform/address/list-payee-address/{user_id}
Retrieves all saved addresses for an existing payee contact.

This endpoint will:
- Verify the payee exists and belongs to the specified user
- Fetch the payee’s saved addresses
- Return the addresses along with a `total_records` count

Each payee can have up to 5 addresses.



# Overview
Source: https://developer.paywint.com/api-reference/payees/addresses/overview

Create, list, update, and delete mailing addresses saved for a user's payees.

Payee Addresses allow you to store and manage mailing destinations for each payee.\
These addresses are commonly used when sending physical check payments, and each payee can maintain multiple saved locations.

You can:

* Add a new address for a payee
* Retrieve the full list of addresses saved for a payee
* Update an existing address
* Delete an address that is no longer needed

Every address is stored under a **user → payee → address** structure, ensuring that information is organized and linked to the correct recipient.

***

## Available APIs

<CardGroup>
  <Card title="Add Payee Address" icon="plus" href="/api-reference/payees/addresses/add">
    Create a new mailing address for a payee.
  </Card>

  <Card title="List Payee Addresses" icon="list" href="/api-reference/payees/addresses/list">
    Retrieve all addresses associated with a payee.
  </Card>

  <Card title="Update Payee Address" icon="edit" href="/api-reference/payees/addresses/update">
    Modify an existing payee address.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Delete Payee Address" icon="trash" href="/api-reference/payees/addresses/delete">
    Remove a saved address from a payee's profile.
  </Card>
</CardGroup>

***

## How Payee Addresses Work

Payee Addresses are helpful when:

* A payee has multiple office locations
* A payee frequently changes their mailing destination
* You need to select where physical checks should be mailed

Each payee can store up to **20 addresses**, allowing flexible address management across different locations and business units.

### Address Accuracy

Because addresses are provided through your application,\
**you should ensure payees review and confirm their address details before mailing checks**.\
This helps maintain accurate delivery information and reduces the risk of returned or delayed mailings.

***

## Best Practices

* Use meaningful names (e.g., “Headquarters”, “Billing Office”, “Warehouse”)
* Validate ZIP codes and country formats in your UI
* Remove outdated addresses to keep payee data organized


# Update Payee Address
Source: https://developer.paywint.com/api-reference/payees/addresses/update

PATCH /api/platform/address/update-payee-address/{user_id}



# Add Payee Bank Account
Source: https://developer.paywint.com/api-reference/payees/bank-accounts/add

POST /api/platform/accounts/add-payee-account/{user_id}
Add a bank account for a specific payee.

This endpoint enables platforms to:
- Register a new bank account for a payee associated with a user
- Store account details of payee



# Delete Payee Bank Account
Source: https://developer.paywint.com/api-reference/payees/bank-accounts/delete

DELETE /api/platform/accounts/delete-payee-account/{user_id}
This endpoint deletes a specific bank account linked to a payee.

- Returns a confirmation message upon successful deletion



# Get Payee Bank Account
Source: https://developer.paywint.com/api-reference/payees/bank-accounts/get

POST /api/platform/accounts/get-payee-account/{user_id}
This endpoint retrives details of a specific bank account linked to a payee.



# List Payee Bank Accounts
Source: https://developer.paywint.com/api-reference/payees/bank-accounts/list

POST /api/platform/accounts/list-payee-account/{user_id}
This endpoint returns all active bank accounts linked to a specific payee.

- Requires a valid `user_id` and payee reference
- Returns a list of bank accounts details of the payee



# Overview
Source: https://developer.paywint.com/api-reference/payees/bank-accounts/overview

Add, retrieve, list, and delete bank accounts saved for a user's payees.

Payee Bank Accounts allow you to store and manage external bank accounts for the individuals or businesses a user pays.\
These accounts can be selected when sending ACH payments or bank-based payouts.

You can:

* Add a bank account for a payee
* Retrieve details of a saved payee bank account
* List all bank accounts linked to a payee
* Remove an account when it is no longer needed

Each bank account is tied to both a **user** and one of their **payees**, keeping records organized and easy to manage.

***

## Available APIs

<CardGroup>
  <Card title="Add Payee Bank Account" icon="plus" href="/api-reference/payees/bank-accounts/add">
    Register a new external bank account for a payee.
  </Card>

  <Card title="Get Payee Bank Account" icon="bank" href="/api-reference/payees/bank-accounts/get">
    Retrieve complete details for a specific payee bank account.
  </Card>

  <Card title="List Payee Bank Accounts" icon="list" href="/api-reference/payees/bank-accounts/list">
    View all stored bank accounts for a payee.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Delete Payee Bank Account" icon="trash" href="/api-reference/payees/bank-accounts/delete">
    Remove a bank account from a payee’s profile.
  </Card>
</CardGroup>

***

## How Payee Bank Accounts Work

Payee bank accounts are maintained separately from a user’s own bank accounts.\
They are typically used when:

* A user pays payees through ACH
* A payee prefers receiving funds directly into their bank
* Multiple payees require different payout destinations

### Accuracy & Confirmation

Since bank information is added directly through your application, **user should confirm the account details with the payee before using it for payouts**.\
This ensures correctness and follows common industry practice for external recipient bank accounts.

(There is no micro-deposit verification for payee bank accounts, because they are owned by the recipient—not the sender—and verification typically happens through your platform’s own onboarding or validation process.)

***

## Best Practices

* Allow users to double-check routing and account numbers before saving
* Use clear nicknames (e.g., “Business Checking – Wells Fargo”) to help identify accounts
* Mask account numbers in your UI to protect sensitive data
* Remove old or unused bank accounts to keep the payee’s profile clean


# Add Payee Card
Source: https://developer.paywint.com/api-reference/payees/cards/add

POST /api/platform/card/add-payee-card/{user_id}
- Add a new payment card to a specific payee for the user.
- Use this to save payee card details for future transactions.



# Delete Payee Card
Source: https://developer.paywint.com/api-reference/payees/cards/delete

DELETE /api/platform/card/delete-payee-card/{user_id}
This endpoint deletes a specific card linked to a payee.

- Returns a confirmation message upon successful deletion



# Get Payee Card
Source: https://developer.paywint.com/api-reference/payees/cards/get

POST /api/platform/card/get-payee-card/{user_id}
This endpoint retrieves details of a specific card linked to a payee.



# List Payee Cards
Source: https://developer.paywint.com/api-reference/payees/cards/list

POST /api/platform/card/list-payee-card/{user_id}
This endpoint returns all cards linked to a specific payee.

- Returns a list of saved cards including nickname, masked number, and expiration



# Overview
Source: https://developer.paywint.com/api-reference/payees/cards/overview

Add, retrieve, list, and delete payment cards saved for a user's payees.

Payee Cards allow your users to save and manage payment cards for their payees.\
These cards can be selected when sending card-based payouts or reimbursements.

You can:

* Add a new card for a payee
* Retrieve a saved payee card
* List all cards associated with a payee
* Delete a card when it is no longer needed

Payee cards are stored under a specific **user → payee** relationship, keeping each card organized and scoped to the correct recipient.

***

## Available APIs

<CardGroup>
  <Card title="Add Payee Card" icon="plus" href="/api-reference/payees/cards/add">
    Save a new card to a payee’s profile.
  </Card>

  <Card title="Get Payee Card" icon="credit-card" href="/api-reference/payees/cards/get">
    Retrieve details for a specific saved card.
  </Card>

  <Card title="List Payee Cards" icon="list" href="/api-reference/payees/cards/list">
    View all cards stored for a payee.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Delete Payee Card" icon="trash" href="/api-reference/payees/cards/delete">
    Remove a saved card from a payee's account.
  </Card>
</CardGroup>

***

## How Payee Cards Work

Payee cards are managed separately from the user's own cards.\
They are typically used when:

* A user needs to send card-based payouts to a payee
* A payee requests a specific card to receive funds
* Multiple payees require different payout destinations

### Accuracy & Confirmation

Since payee card details are supplied through your application,\
**user should confirm the card details with the payee before using it for payouts**.

This follows standard industry practice for recipient-side payment methods,\
and provides an extra layer of assurance before attempting a transfer.

***

## Best Practices

* Display only masked card numbers in your UI
* Allow clear nicknames such as John's Visa” or "Ham's Personal Mastercard”
* Encourage users to confirm expiration dates before saving
* Remove outdated or expired cards to keep the payee’s profile current


# Create Payee
Source: https://developer.paywint.com/api-reference/payees/create

POST /api/platform/payee/create/{user_id}
Creates a new payee under the specified user.

This endpoint enables platforms to:
- Register a new payee for an existing user
- Associate contact details like name, email, and phone
- At least one is required: provide either an email or a phone number with country code.



# Delete Payee
Source: https://developer.paywint.com/api-reference/payees/delete

DELETE /api/platform/payee/delete/{user_id}
Delete a specific payee associated with a user.

This endpoint enables platforms to:
- Remove a payee from a user's saved contacts



# Get Payee
Source: https://developer.paywint.com/api-reference/payees/get

POST /api/platform/payee/get/{user_id}
Retrieves the contact details of a specific payee associated with a user.

This endpoint enables platforms to:
- Fetch payee information saved under a specific user



# List Payees
Source: https://developer.paywint.com/api-reference/payees/list

POST /api/platform/payee/list-payee/{user_id}
Retrieve all payees associated with a specific user, ordered by most recently added.



# Overview
Source: https://developer.paywint.com/api-reference/payees/overview

Create, update, retrieve, list, and delete payees linked to a user.

Payees represent the individuals or businesses that a user can send payments to.\
This includes contacts receiving payments through ACH, cards, wallet transfers, mailed checks, or any supported method.

The Payee Management API allows you to store and maintain a user’s payment recipients so they can quickly send payments without re-entering details each time.

***

## What This API Covers

With the Payee Management APIs, you can:

* Create new payees for a user
* Store basic contact information such as name, email, and phone
* Update payee details
* Retrieve a specific payee
* List all payees associated with a user
* Remove a payee when no longer needed

A payee may include either an **email** or a **phone number with country code**, and a name is always required.

***

## Available APIs

<CardGroup>
  <Card title="Create Payee" icon="user-plus" href="/api-reference/payees/create">
    Register a new payee under a specific user.
  </Card>

  <Card title="Update Payee" icon="pencil" href="/api-reference/payees/update">
    Modify the name of an existing payee.
  </Card>

  <Card title="Get Payee" icon="user" href="/api-reference/payees/get">
    Retrieve stored contact details for a specific payee.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="List Payees" icon="list" href="/api-reference/payees/list">
    Fetch all payees created under a user, with pagination support.
  </Card>

  <Card title="Delete Payee" icon="trash" href="/api-reference/payees/delete">
    Remove a payee from the user’s contact list.
  </Card>
</CardGroup>

***

## When Payees Are Used

Payees are used whenever a user sends a payment to another person or entity, including:

* ACH or card-based payments
* Wallet-to-wallet transfers
* Mailed check payments

Storing payees makes the payment flow simpler, faster, and less error-prone.

***

## Manage Payee's

<Steps>
  <Step title="1. Create a payee for the user">
    Use <code>[Create Payee](/api-reference/payees/create)</code> with the payee’s name and at least one contact method.
  </Step>

  <Step title="2. Retrieve or list payees when preparing a payment">
    Before sending a payment, fetch a specific payee or list all payees for selection.
  </Step>

  <Step title="3. Update payee details when needed">
    The payee’s name can be modified using\
    <code>[Update Payee](/api-reference/payees/update)</code>.
  </Step>

  <Step title="4. Delete unused payees">
    If a payee is no longer relevant, remove them using\
    <code>[Delete Payee](/api-reference/payees/delete)</code>.
  </Step>
</Steps>

***

## Best Practices

* Require users to provide at least one reliable contact detail (email or phone)
* Display the payee name and contact details to confirm the correct recipient
* Encourage users to keep their payee list up-to-date
* Use pagination when listing payees for users with large recipient lists


# Update Payee
Source: https://developer.paywint.com/api-reference/payees/update

PUT /api/platform/payee/update/{user_id}
Update payee name



# Create Checkout SDK Token
Source: https://developer.paywint.com/api-reference/payments/checkout/create-checkout-token

POST /api/checkout/token/platform
Generates a short-lived, tamper-proof checkout token for initializing Paywint Inline Checkout.

This endpoint performs the following actions:
- Authenticates the platform using `X-Platform-ID` and `X-Signature`
- Resolves or creates a per-initiator signing secret
- Issues a signed checkout token embedding initiator and payer context
- Returns the token and its expiry for use by the frontend SDK



# Create Payment Link
Source: https://developer.paywint.com/api-reference/payments/checkout/create-payment-link

POST /api/platform/payment/create-payment-link/{user_id}
Generates a secure payment link to collect wallet-based payments from others.

This endpoint allows platforms to:
- Create a new payment link for a verified user
- Provides a shareable URL that can be sent to others for payment collection
- Returns the generated payment ID and link



# Inline Checkout SDK
Source: https://developer.paywint.com/api-reference/payments/checkout/inline-checkout-sdk

Embed Paywint Inline Checkout directly in your application.

The Paywint Inline Checkout SDK renders a managed checkout component inside your page. Your backend creates a short-lived [checkout token](/api-reference/payments/checkout/create-checkout-token), then your frontend passes that token to the SDK with the payment configuration.

## Load the SDK

Load the Paywint Checkout SDK and initialize the checkout mount point.

```html theme={null}
<head>
  <script>window.$paywint=window.$paywint||{};$paywint.checkout=$paywint.checkout||{ready:function(){}};</script>
  <script src="https://YOUR_PAYWINT_SDK_HOST/checkout.js" defer></script>
</head>
<body>

  <!-- Element to mount the checkout SDK -->
  <div id="checkout-root"></div>
  
  <!-- Optional custom submit button -->
  <button id="host-submit-button" type="button">Submit From Host</button>

  <script>
    $paywint.checkout.ready = () => {
      const pwCheckout = new PaywintCheckout();

      const pwCheckoutConfig = {
        token: "CHECKOUT_TOKEN_FROM_YOUR_BACKEND",
        payOptions: ["card", "wallet"],
        amount: 120,
        currency: "USD",
        invoice_number: "INV-1001",
        description: "Order #1001",
        hide_submit_button: false,
        style: {
          "pw-border-color": "#d9e6f4",
          "pw-active-border-color": "#025865",
          "pw-background-color": "#ffffff",
          "pw-text-color": "#1e293b",
          "pw-input-border-color": "1px solid #cbd5e1",
          "pw-input-radius": "8px",
          "pw-input-height": "40px",
          "pw-submit-button-background-color": "#000000",
          "pw-submit-button-text-color": "#ffffff",
          "pw-checkout-font": "Inter, sans-serif"
        }
      };

      const payerAddressData = {
        payer_first_name: "Jane",
        payer_last_name: "Doe",
        payer_address_line_1: "123 Main Street",
        payer_city: "New York",
        payer_state: "NY",
        payer_zip: "10001",
        payer_country: "US"
      };

      pwCheckout
        .init("#checkout-root", pwCheckoutConfig, (event) => {
          console.log("Paywint event:", event);
        })
        .then(() => {
          pwCheckout.updatePayorAddress(payerAddressData);

          document.getElementById("host-submit-button")?.addEventListener("click", () => {
            pwCheckout.triggerSubmit();
          });
        })
        .catch((error) => {
          document.getElementById("checkout-root").textContent = error?.message || "Failed to initialize checkout.";
        });
    };
  </script>
</body>
```

<Info>
  Replace `https://YOUR_PAYWINT_SDK_HOST/checkout.js` with the checkout SDK URL provided for your environment.

  | Environment  | Checkout.js URL                                  |
  | ------------ | ------------------------------------------------ |
  | `Production` | `https://script.paywint.com/checkout.js`         |
  | `Sandbox`    | `https://sandbox.script.paywint.com/checkout.js` |
</Info>

## Configuration

Pass the configuration object as the second argument to `init(selector, config, eventsCB)`.

| Field                | Type               | Required    | Description                                                                              |
| -------------------- | ------------------ | ----------- | ---------------------------------------------------------------------------------------- |
| `token`              | `string`           | Yes         | Checkout token created by your backend.                                                  |
| `payOptions`         | `string[]`         | Yes         | Payment methods to show. Supported values include `card` and `wallet`.                   |
| `amount`             | `number`           | Yes         | Payment amount. The SDK validates that this matches the token context.                   |
| `currency`           | `string`           | Recommended | ISO currency code, for example `USD`.                                                    |
| `invoice_number`     | `string`           | Optional    | Your invoice or order reference.                                                         |
| `description`        | `string`           | Optional    | Description shown in checkout and returned in events where applicable.                   |
| `hide_submit_button` | `boolean \| null`  | Optional    | Set to `true` when you want to submit from your own host button using `triggerSubmit()`. |
| `style`              | `object \| string` | Optional    | CSS variable overrides for the checkout component.                                       |

## Payer Address

Use `updatePayorAddress()` after `init()` resolves. You can call it again whenever the payer edits their billing address in your host page.

```js theme={null}
pwCheckout.updatePayorAddress({
  payer_first_name: "Jane",
  payer_last_name: "Doe",
  payer_address_line_1: "123 Main Street",
  payer_city: "New York",
  payer_state: "NY",
  payer_zip: "10001",
  payer_country: "US"
});
```

## Custom Submit Button

If your integration hides the SDK submit button, call `triggerSubmit()` from your own button after `init()` completes.

```js theme={null}
document.getElementById("host-submit-button")?.addEventListener("click", () => {
  pwCheckout.triggerSubmit();
});
```

## Events

Pass an event callback as the third argument to `init()`. The SDK calls this function as checkout state changes.

```js theme={null}
pwCheckout.init("#checkout-root", pwCheckoutConfig, (event) => {
  console.log(event.event, event.message, event.data);
});
```

Common event payloads include an `event` name, a human-readable `message`, and optional `data` for the payment or verification step.

## Styling

The `style` configuration accepts an object of CSS variable overrides. Keys may be provided with or without the leading `--`.

```js theme={null}
style: {
    "pw-border-color": "#d9e6f4",
    "pw-border-width": "2px",
    "pw-active-border-color": "#025865",
    "pw-disabled-border-color": "#f8fff0",
    "pw-disabled-opacity": "0.5",
    "pw-background-color": "#ffffff",
    "pw-text-color": "#1e293b",
    "pw-input-label-text-color": "#1e293b",
    "pw-subtext-text-color": "#64748b",
    "pw-muted-background-color": "rgb(127 127 127 / 0.12)",
    "pw-error-text-color": "#ff5757",
    "pw-success-surface-start-background-color": "#f0fdf4",
    "pw-success-surface-end-background-color": "#dcfce7",
    "pw-success-icon-background-color": "#dcfce7",
    "pw-success-icon-color": "#16a34a",
    "pw-success-text-color": "#16a34a",
    "pw-input-border-color": "1px solid #cbd5e1",
    "pw-input-radius": "8px",
    "pw-input-height": "40px",
    "pw-input-font-size": "18px",
    "pw-input-background-color": "#ffffff",
    "pw-submit-button-background-color": "#000000",
    "pw-submit-button-text-color": "#ffffff",
    "pw-submit-button-radius": "8px",
    "pw-file-upload-background-color": "#ffffff",
    "pw-file-upload-text-color": "#000000",
    "pw-file-upload-button-radius": "8px",
    "pw-file-upload-button-height": "44px",
    "pw-file-upload-border-color": "#000000",
    "pw-file-upload-border-width": "2px",
    "pw-file-upload-border-style": "dotted",
    "pw-checkout-font": "Inter, sans-serif",
    "pw-otp-gap": "10px",
    "pw-otp-width": "50px",
    "pw-otp-height": "40px",
    "pw-otp-font-size": "18px",
    "pw-otp-border-color": "1px solid #cbd5e1",
    "pw-otp-radius": "8px",
    "pw-otp-background-color": "#ffffff",
    "pw-otp-text-color": "#1e293b",
    "pw-otp-placeholder-text-color": "#94a3b8",
    "pw-otp-focus-border-color": "#025865"
}
```

<Note>
  When `pw-checkout-font` is provided, the SDK does not load its default Inter font stylesheet. Load your custom font on the host page if the font is not already available.
</Note>

## SDK Methods

| Method                             | Description                                                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `init(selector, config, eventsCB)` | Mounts checkout into an element matching the selector. The selector must be an ID selector such as `#checkout-root`. |
| `updatePayorAddress(address)`      | Updates payer billing address data after checkout has initialized.                                                   |
| `triggerSubmit()`                  | Programmatically submits checkout. Use this for host-controlled submit buttons.                                      |


# Overview
Source: https://developer.paywint.com/api-reference/payments/checkout/overview

Securely accept payments online.

Use a prebuilt checkout page to start accepting online payments.

<Tabs>
  <Tab title="Embedded form (iFrame)">
    Embed the Paywint checkout inside your website using an iFrame.\
    This option keeps customers inside your UI while Paywint handles all sensitive data and compliance.

    <Frame>
      <img alt="Embedded checkout form" />
    </Frame>

    <Steps>
      <Step title="Create a payment link">
        Your backend calls
        [Create Payment Link](/api-reference/payments/checkout/create-payment-link)
        with the amount and payer information.
      </Step>

      <Step title="Receive the checkout URL">
        Paywint returns a <code>payment\_link</code> URL representing the checkout session.
      </Step>

      <Step title="Embed the checkout">
        You load the <code>payment\_link</code> inside an <code>\<iframe></code> on your website.
      </Step>

      <Step title="Customer completes the payment">
        The customer reviews and completes the payment inside the embedded checkout.
      </Step>

      <Step title="Receive lifecycle webhooks">
        Paywint sends webhook notifications to your server as the payment progresses\
        (session opened, status updates, and final result).\
        For full event details, see the [Webhooks](/webhooks/overview) documentation.
      </Step>

      <Step title="Redirect the customer">
        After the checkout finishes, Paywint redirects the customer to the **Redirect URL**\
        that you configure in your merchant dashboard.\
        The redirect includes the final payment status, and your application should handle\
        the next steps based on that status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Paywint-hosted page (redirect)">
    Redirect customers to Paywint-hosted checkout page.

    This option gives you the fastest setup with no front-end integration work.
    Customers leave your site, complete the payment on Paywint’s secure checkout page,
    and are redirected back to you once the payment finishes.

    <Frame>
      <img alt="Hosted checkout page" />
    </Frame>

    <Steps>
      <Step title="Create a payment link">
        Your backend calls
        [Create Payment Link](/api-reference/payments/checkout/create-payment-link)
        with the relevant payment details.
      </Step>

      <Step title="Receive the checkout URL">
        Paywint returns a <code>payment\_link</code> URL that represents the hosted checkout page.
      </Step>

      <Step title="Redirect the customer">
        Your front-end navigates the customer to the <code>payment\_link</code>\
        (typically by opening it in a new window or redirecting the browser).
      </Step>

      <Step title="Customer completes the payment">
        The customer completes the entire checkout process on Paywint’s hosted page.\
        All sensitive data entry and validation is handled by Paywint.
      </Step>

      <Step title="Receive lifecycle webhooks">
        As the payment moves through different states, Paywint sends corresponding webhook
        notifications to your server.\
        Refer to the [Webhooks](/webhooks/overview) documentation for all available event types.
      </Step>

      <Step title="Customer is returned to your application">
        After the checkout completes, Paywint redirects the customer to the **Redirect URL**\
        configured in your merchant dashboard.\
        The redirect includes the final payment status, and your application should display\
        a confirmation, error message, or next step based on that status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Inline Checkout SDK">
    Build a fully custom checkout experience using Paywint-managed UI components.
    Your backend issues a short-lived checkout token, the frontend SDK handles OTP verification,
    card validation, and payment — all within your own UI.

    <Frame>
      <img alt="Inline Checkout" />
    </Frame>

    <Steps>
      <Step title="Issue a checkout token (your backend)">
        Your backend calls the appropriate token endpoint, passing the payer identity,
        payment amount, currency, and scope.

        Paywint returns a short-lived `checkout_token` (valid for 30 minutes).

        * [Generate Checkout Token Here](/api-reference/payments/checkout/create-checkout-token)
      </Step>

      <Step title="Initialize the SDK (frontend)">
        Pass the `checkout_token` to the Paywint Inline Checkout SDK along with the
        payment amount and currency.

        ```js theme={null}
        const pwCheckoutConfig = {
          token: "CHECKOUT_TOKEN_FROM_YOUR_BACKEND",
          payOptions: ["card", "wallet"],
          amount: 120,
          currency: "USD",
          invoice_number: "INV-1001",
          description: "Order #1001"
        }
        pwCheckout.init("#checkout-root", pwCheckoutConfig, (event) => {
          console.log(event.event, event.message, event.data);
        });
        ```

        * [View Complete Implementation Here](/api-reference/payments/checkout/inline-checkout-sdk)
      </Step>

      <Step title="Receive lifecycle webhooks (your backend)">
        As the payment moves through states, Paywint sends webhook notifications
        to your server. See the [Webhooks](/webhooks/overview) documentation for
        all available event types and payload shapes.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Create Payment
Source: https://developer.paywint.com/api-reference/payments/create

POST /api/platform/payment/create-payment
Initiates a payment from a user to one of their registered payees.

This endpoint performs the following actions:
- Accepts payment details including payer, payee, amount, and selected payment method
- Calculates any applicable processing and delivery fees
- Executes the relevant payment flow based on the delivery method (WALLET, CARD, ACH, PW_BANK, RTP, FEDNOW)
- Sends transaction notifications upon successful payment



# Get Payment Details
Source: https://developer.paywint.com/api-reference/payments/get

GET /api/platform/payment/get-payment/{payment_id}
Fetch the details of a specific payment using its unique ID.

This endpoint:
- Retrieves a payment record by its `id`
- Ensures the request is made by an authenticated platform via API key
- Returns the payment data in a standardized format



# List Payments
Source: https://developer.paywint.com/api-reference/payments/list

POST /api/platform/payment/list-payment
Retrieve a list of all payments associated with the platform.



# List User Received Payments
Source: https://developer.paywint.com/api-reference/payments/list-received

POST /api/platform/payment/list-received-payment/{user_id}
Retrieve all payment records where the specified user is the payee.

- Returns a list of payments received by the user



# List User Payments
Source: https://developer.paywint.com/api-reference/payments/list-sent

POST /api/platform/payment/list-payment/{user_id}
Retrieve all payment records where the specified user is the payer.

- Returns a list of payments initiated by the user



# Mail Check
Source: https://developer.paywint.com/api-reference/payments/mail-check

POST /api/platform/payment/mail-check/{user_id}
Sends a physical check payment by mail to a specified payee on behalf of a platform user.

This endpoint will:
- Download and validate the check attachment (PDF only, max 7MB, up to 10 pages)
- Calculate processing fees based on mail type and attachment pages
- Deduct the total amount (payment + fees) from the user's wallet
- Generate and mail a physical check to the payee's address
- Create payment and check records for tracking

Supported mail types include USPS First Class, USPS Certified, Overnight, and Two-Day delivery.
Processing fees vary by mail type and include additional charges for attachment pages.



# Overview
Source: https://developer.paywint.com/api-reference/payments/overview

Create, track, and manage payments using wallet, ACH, card, Paywint Bank, or mailed checks.

The Payments API enables secure and flexible money movement between users and payees.\
Payments can be funded through a user’s **wallet**, **linked card**, **bank (ACH)**, or **Paywint Bank account**, or delivered by **mailing a physical check**.

***

## Send & Manage Payments

<CardGroup>
  <Card title="Create Payment" icon="dollar" href="/api-reference/payments/create">
    Initiate a payment from a user to another user or payee.\
    Handles validation, fees, settlement flow, and lifecycle events.
  </Card>

  <Card title="Mail Check" icon="money-check" href="/api-reference/payments/mail-check">
    Create and mail a physical check to a payee’s address, with fee calculation and attachment support.
  </Card>

  <Card title="Get Payment" icon="receipt" href="/api-reference/payments/get">
    Retrieve full details of a payment including status, timestamps, fees, and method.
  </Card>

  <Card title="List Payments" icon="list" href="/api-reference/payments/list">
    List all payments across your platform with filtering and pagination.
  </Card>

  <Card title="List User Payments" icon="list" href="/api-reference/payments/list-sent">
    Retrieve all payments initiated by a specific user.
  </Card>

  <Card title="List Received Payments" icon="list" href="/api-reference/payments/list-received">
    Retrieve all payments received by a specific user.
  </Card>
</CardGroup>

***

## How Payments Work

Before sending a payment, ensure that:

1. **The payer is a registered user**
2. **The recipient exists as payee with a saved card, bank, or mailing address**

Once this setup is complete, payments can be created using the\
**[Create Payment](/api-reference/payments/create)** API.

***

## Supported Payment Methods

### **Wallet**

**Delivery:** Instant\
**Funding source:** User wallet\
**Notes:** Fastest method; funds are transferred immediately.

***

### **Card**

**Delivery:** 1–2 business days\
**Funding source:** Linked card\
**Notes:** Uses standard card settlement timelines.

***

### **Bank ACH**

**Delivery:** 3–4 business days\
**Funding source:** Linked bank account\
**Notes:** Well suited for high-value transfers; follows ACH settlement timelines.

***

### **Paywint Bank Account**

**Delivery:** Instant\
**Funding source:** Paywint digital bank account\
**Notes:** Fully traceable and optimized for transfers.

***

### **Physical Check**

**Delivery:** Based on mail type\
**Funding source:** Wallet\
**Notes:** Supports USPS First Class, Certified, Two-Day, and Overnight; optional PDF attachments up to 10 pages (7MB max).

***

For collecting money **from customers** through checkout or invoicing, see:\
**[Accept Payments](/api-reference/payments/checkout/overview)**


# List Paywint Bank Accounts
Source: https://developer.paywint.com/api-reference/paywint-bank-accounts/list

GET /api/platform/accounts/list-pw-banks/{user_id}
Retrieves all Paywint bank accounts linked to the specified user, ordered by most recently added.



# List Paywint Bank Account Transactions
Source: https://developer.paywint.com/api-reference/paywint-bank-accounts/list-transactions

POST /api/platform/accounts/list-pw-transactions/{user_id}
Retrieves a paginated list of Paywint bank transactions for a specific user.

This endpoint allows platforms to:
- View transaction history associated with a user’s Paywint bank account
- Filter and paginate transactions by account and user
- Access transaction details such as amount, type, and date

When this endpoint is called for the first time, the system automatically initiates a
background sync to fetch the latest Paywint transactions.
During this initial sync (which may take up to **one minute**), the response will contain
only previously available transactions.

To view newly synced transactions, call this endpoint again after **one minute**.

Returns the total number of transactions and a list of transaction records.



# Open Paywint Bank Account
Source: https://developer.paywint.com/api-reference/paywint-bank-accounts/open

POST /api/platform/accounts/open-pw-bank-account/{user_id}
Creates a new Paywint bank account for an eligible user.

This endpoint now supports two Paywint bank account types:

### **Account Types**
- **paywint_savings** - Requires only **KYC approval**
- **paywint_business** - Requires **both KYC and KYB approval**

A nickname must be provided for the new account, and the system validates that:
- The bank nickname does not already exist for the user
- The user has not exceeded their allowed Paywint bank account limit

### **Eligibility Criteria**
- **For paywint_savings:**
  - User's **KYC must be approved**

- **For paywint_business:**
  - User's **KYC must be approved**
  - User's **KYB must be approved**



# Overview
Source: https://developer.paywint.com/api-reference/paywint-bank-accounts/overview

Open and manage Paywint–issued digital bank accounts for your users.

Paywint Bank Accounts provide users with a verified digital bank account issued directly by Paywint.\
These accounts function like standard bank accounts but operate entirely digitally.\
Once opened, users can use their Paywint bank account to make payments, receive transfers, and handle various financial operations both within and outside Paywint.

***

## Account Types

#### PAYWINT\_SAVINGS

For individual users.\
Requires the user to have **KYC verified**.

#### PAYWINT\_BUSINESS

For business or entity users.\
Requires the user to have **both KYC and KYB verified**.

Each account requires a unique nickname, and users may open multiple Paywint accounts within allowed limits.

***

## How It Works

<Steps>
  <Step title="1. Check user eligibility">
    Ensure the user has completed the required verification:

    * PAYWINT\_SAVINGS: KYC approval
    * PAYWINT\_BUSINESS: KYC and KYB approval
  </Step>

  <Step title="2. Open a Paywint bank account">
    Call <code>[Open Paywint Bank Account](/api-reference/paywint-bank-accounts/open)</code>
    with the account type and a unique nickname.\
    The account is created instantly if the user is eligible.
  </Step>

  <Step title="3. Use the new bank account">
    Once created, the user receives access to a fully functional digital bank account that can be used to:

    * Make payments within Paywint
    * Receive incoming transfers
    * Perform internal and external fund movements
    * Use the account like a normal bank account for supported external purposes
  </Step>

  <Step title="4. View account transactions">
    Use <code>[List Paywint Bank Account Transactions](/api-reference/paywint-bank-accounts/list-transactions)</code>
    to retrieve transaction history for the Paywint bank account.
  </Step>
</Steps>

***

## Transaction Sync Behavior

* When transaction history is requested for the first time, Paywint initiates a one-time background sync to fetch the latest bank transactions.
* This process may take up to one minute.
* Newly synced transactions will appear in subsequent requests.

***

## Available APIs

<CardGroup>
  <Card title="Open Paywint Bank Account" href="/api-reference/paywint-bank-accounts/open" icon="external-link">
    Create a new Paywint digital bank account.
  </Card>

  <Card title="List Transactions" href="/api-reference/paywint-bank-accounts/list-transactions" icon="list">
    Retrieve all transactions associated with a Paywint bank account.
  </Card>
</CardGroup>


# Paywint Bank Account Withdrawal
Source: https://developer.paywint.com/api-reference/paywint-bank-accounts/withdrawal

POST /api/platform/withdrawals/transfer-from-pw-bank/{user_id}
Transfers funds from a platform user's Paywint bank account to their wallet, card, or ACH bank account.

This endpoint:
- Uses the user's Paywint bank account as the funding source
- Supports wallet, card, and ACH destinations
- Returns the withdrawal transaction details upon successful processing



# Create User
Source: https://developer.paywint.com/api-reference/users/create

POST /api/platform/users/create
Creates a new user account into the platform.

This endpoint enables platforms to:
- Register a new user
- Automatically generate a wallet for the user
- Initialize default settings for the newly created user
- At least one is required: provide either an email or a phone number with country code.



# Get User
Source: https://developer.paywint.com/api-reference/users/get

GET /api/platform/users/get/{user_id}
Retrieve user details for a specific user ID within the platform.

This endpoint is used by platform admins to:
- Fetch a single user by their unique ID
- Ensure the user belongs to the platform making the request
- Return structured user data if found



# List Users
Source: https://developer.paywint.com/api-reference/users/list

POST /api/platform/users/list
Retrieve a list of users created under the current platform.



# Overview
Source: https://developer.paywint.com/api-reference/users/overview

Register and manage users in Paywint to enable payments, wallets, and other financial services.

User management is the foundation of your Paywint integration.\
Every financial action—payments, wallet transfers, payees, card linking, and checkout—starts with a registered user.

***

## Integrate User Management

Use the User Management API to create, list, and retrieve users.\
These endpoints are required for onboarding users into your platform and enabling any financial features.

<CardGroup>
  <Card title="Create User" icon="user-plus" href="/api-reference/users/create">
    Register a new user under your platform. Required before enabling financial actions.
  </Card>

  <Card title="List Users" icon="users" href="/api-reference/users/list">
    Retrieve all users associated with your platform account.
  </Card>

  <Card title="Get User" icon="user-check" href="/api-reference/users/get">
    Fetch complete user details including profile, compliance status, and linked methods.
  </Card>
</CardGroup>

***

## User Workflow with Paywint

<Steps>
  <Step title="Register the user">
    Call [Create User](/api-reference/users/create) to create a Paywint user record and obtain a Paywint User ID.
  </Step>

  <Step title="Compliance requirements">
    Wallet-to-wallet payments do not require any compliance checks.\
    Other payment methods—such as bank transfers, ACH, or card-based payouts—may require the user to complete necessary [KYC](/api-reference/compliance/kyc/create-enquiry-link)/[KYB](/api-reference/compliance/kyb/submit) steps depending on usage and regulatory rules.
  </Step>

  <Step title="User can access financial features">
    Users can
    [add bank accounts](/api-reference/bank-accounts/add),
    [add cards](/api-reference/cards/add),
    [create payees](/api-reference/payee/create-payee),
    and use their [Paywint wallet](/api-reference/wallet/get).\
    Most features are available by default, and some advanced capabilities may require contacting the Paywint support team.
  </Step>

  <Step title="Start processing payments">
    Users can immediately make wallet-to-wallet payments.\
    For other payment types, usage depends on whether required verification steps have been completed.
  </Step>
</Steps>

***

## Merchant Dashboard

Manage users directly from the merchant dashboard.\
View user details, verification status, wallet balances, payment activity, and more.

<Frame>
  <img alt="User management dashboard" />
</Frame>

<CardGroup>
  <Card title="Sandbox Dashboard" icon="flask-vial" href="https://sandbox.merchant.paywint.com">
    Access your sandbox merchant dashboard for testing and integration.
  </Card>

  <Card title="Production Dashboard" icon="bullseye" href="https://merchant.paywint.com">
    Manage live users and financial operations in production.
  </Card>
</CardGroup>

***

## Best Practices

* Always store the **Paywint User ID** to map internal users to Paywint.
* Ensure [KYC](/api-reference/compliance/kyc/create-enquiry-link)/[KYB](/api-reference/compliance/kyb/submit) is completed before initiating payments.
* Use the dashboard for manual review, troubleshooting, and support operations.


# Fund Wallet / ACH Pull
Source: https://developer.paywint.com/api-reference/wallet/fund

POST /api/platform/wallet/fund-wallet/{user_id}
Initiates the process of funding a user's wallet via the platform using a specified payment method.

This endpoint:
- Starts the wallet funding flow using bank account
- Checks for any existing incomplete funding transactions before proceeding



# Get Wallet
Source: https://developer.paywint.com/api-reference/wallet/get

GET /api/platform/wallet/get/{user_id}
Retrieves the wallet information for a specific user.

This endpoint:
- Fetches the user's wallet details, including balance and metadata
- Automatically creates a wallet if one does not already exist
- Returns Current and Available wallet balances



# Overview
Source: https://developer.paywint.com/api-reference/wallet/overview

Access, fund, and withdraw from a user’s Paywint wallet.

Every Paywint user automatically receives a wallet when their account is created.\
The wallet stores funds, supports instant internal transfers, and can be used to pay other users or move money to external bank accounts or cards.

This section provides APIs to retrieve wallet details, add funds, and withdraw funds.

***

## What the Wallet Supports

The Paywint wallet functions as a digital balance assigned to each user. It can be used for:

* Holding funds
* Paying other Paywint users
* Funding through a linked bank account
* Withdrawing to a bank account or card
* Using wallet balance as a payment method for transactions

You do not need to create the wallet manually—Paywint creates it automatically upon first retrieval.

***

## Available APIs

<CardGroup>
  <Card title="Get Wallet" icon="wallet" href="/api-reference/wallet/get">
    Retrieve a user's wallet, including current and available balance.
  </Card>

  <Card title="Fund Wallet" icon="upload" href="/api-reference/wallet/fund">
    Add funds to the wallet using the user’s linked bank account.
  </Card>

  <Card title="Withdraw Funds" icon="download" href="/api-reference/wallet/withdraw">
    Move money out of the wallet to a bank account or card.
  </Card>
</CardGroup>

***

## How It Works

<Steps>
  <Step title="Retrieve the wallet">
    Call <code>Get Wallet</code> to fetch a user’s wallet balance.\
    If the wallet does not exist yet, Paywint will automatically create one.
  </Step>

  <Step title="Fund the wallet">
    Use <code>Fund Wallet</code> to transfer money from a linked bank account into the wallet balance.
  </Step>

  <Step title="Withdraw funds">
    Use <code>Withdraw Funds</code> to move money from the wallet to a bank account or card.
  </Step>
</Steps>

***

## Best Practices

* Always call <code>Get Wallet</code> before funding or withdrawing to fetch the latest balance
* Funding uses the user’s verified bank accounts
* Withdrawal methods may require bank or card verification
* Wallet balances update instantly after most internal transfers


# Withdraw Fund
Source: https://developer.paywint.com/api-reference/wallet/withdraw

POST /api/platform/withdrawals/withdraw-fund/{user_id}
Initiates a withdrawal from a platform user’s wallet using a supported transfer method.

This endpoint:
- Processes the withdrawal request based on the selected transfer method (e.g., bank, card, etc.)
- Returns the transaction details upon successful processing



# Authentication
Source: https://developer.paywint.com/get-started/authentication

We use API key based authentication to verify and authorize all requests to the Paywint API.

**All API requests to Paywint must be made over HTTPS and authenticated using an API key.**
Include the API key in the request header as `X-Platform-ID`, and the HMAC-SHA256 signature in `X-Signature`. [Learn how to generate signatures →](/get-started/signature-auth)

The signature should be generated using your platform's secret key and the [canonical string format](/get-started/signature-auth#canonical-string-format): `METHOD + PATH + QUERY + BODY_HASH`

```curl Example Api Call theme={null}
curl -X POST "https://<environment>/api/platform/users/create" \
  -H "Content-Type: application/json" \
  -H "X-Platform-ID: YOUR_API_KEY" \
  -H "X-Signature: GENERATED_SIGNATURE" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "9876543210",
    "phone_country_code": "+1"
  }'

```

Make sure to use the correct API key for the appropriate [environment](/environments). Using the wrong key or URL may result in authentication failures.

Keep your API key secure and never expose it on the client side.

<Note>
  Alternatively, you can use the static signature in the [sandbox environment](/environments#sandbox): `8b3cb99a4b8e24fc7e01d0db635e2e47b80818144fe51400c6c6ae3ecbc84f47`
</Note>

<Card title="How to generate signature" icon="shield" href="/get-started/signature-auth">
  Learn how to generate secure request signatures using your platform’s secret key in our Signature Authentication Guide.
</Card>

***

Need help? Reach out to [support@paywint.com](mailto:support@paywint.com)


# Dashboards
Source: https://developer.paywint.com/get-started/dashboards

We offer Sandbox and Production dashboards to streamline your development and go-live process.

### Choose your dashboard

<CardGroup>
  <Card title="Sandbox Dashboard" icon="flask-vial" href="https://sandbox.merchant.paywint.com">
    For testing and development purposes. Use this dashboard to simulate transactions and integrations in a safe environment.

    [sandbox.merchant.paywint.com](https://sandbox.merchant.paywint.com)
  </Card>

  <Card title="Production Dashboard" icon="bullseye" href="https://merchant.paywint.com">
    Live dashboard for managing real transactions, accounts, and business operations.

    [merchant.paywint.com](https://merchant.paywint.com)
  </Card>
</CardGroup>


# Environments
Source: https://developer.paywint.com/get-started/environments

Accelerate your development cycle using Paywint’s separate environments for testing and live deployment.

## Sandbox

1. Contact [support@paywint.com](mailto:support@paywint.com) to request a sandbox (test) account.
2. You’ll receive credentials to access the [Sandbox Dashboard](https://sandbox.merchant.paywint.com).
3. Navigate to the [Credentials tab](https://sandbox.merchant.paywint.com/app/settings/api-credentials) to obtain your API key for accessing all sandbox APIs.
4. Set the API base URL to: `https://api.sandbox.paywint.com`

## Production

Before switching to production, please contact our support team to enable API access for your production account. We’re happy to assist with any questions or issues during setup.

1. Contact [support@paywint.com](mailto:support@paywint.com) to request a production account.
2. You’ll receive credentials to access the [Production Dashboard](https://merchant.paywint.com).
3. Navigate to the [Credentials tab](https://merchant.paywint.com/app/settings/api-credentials) to obtain your production API key.
4. Set the API base URL to: `https://api.paywint.com`


# Overview
Source: https://developer.paywint.com/get-started/overview

Welcome to the Paywint API documentation.

<img alt="Paywint Banner" />

<img alt="Paywint Banner" />

The Paywint API supercharges your app with powerful payment tools built for speed and simplicity. Whether you're managing users or processing transactions, Paywint makes it effortless to create fast, reliable financial systems. Perfect for developers and businesses ready to streamline their payment workflows, the API delivers everything you need- from managing users and handling payments to automating approvals and beyond.

<CardGroup>
  <Card title="Environments" icon="split" href="/get-started/environments">
    Accelerate your development cycle using Paywint’s separate environments for testing and live deployment.
  </Card>

  <Card title="Dashboards" icon="gauge" href="/get-started/dashboards">
    We offer Sandbox and Production dashboards to streamline your development and go-live process.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Authentication" icon="key" href="/get-started/authentication">
    We use API key based authentication to verify and authorize all requests to the Paywint API.
  </Card>

  <Card title="How to generate signature" icon="shield" href="/get-started/signature-auth">
    Learn how to generate secure request signatures using your platform’s secret key in our Signature Authentication Guide.
  </Card>
</CardGroup>


# Quickstart
Source: https://developer.paywint.com/get-started/quickstart

Start building with the Paywint API — from user creation to payments.

Integrate Paywint’s APIs to enable full payment capabilities — from user creation and verification to wallet funding, transfers, and payouts.\
This guide provides an end-to-end example using the **Sandbox environment** to help you make your first successful API calls.

<CardGroup>
  <Card title="Authentication" icon="key" href="/get-started/authentication">
    Use your API key in the Authorization header to securely call Paywint endpoints.
  </Card>

  <Card title="Environments" icon="split" href="/get-started/environments">
    Run these requests in the Sandbox environment before going live.
  </Card>
</CardGroup>

***

## Monitor Real-Time Events

Paywint sends webhook notifications for important events such as:

* `user.verified`
* `wallet.funding.success`
* `payment.processing`
* `withdrawal.failed`

To learn how to verify webhook signatures and handle retries, visit the [Webhooks Overview](/webhooks/overview).

***

## Test and Go Live

<CardGroup>
  <Card title="Test in Sandbox" icon="flask-vial" href="/get-started/environments">
    Validate your integration safely using sandbox credentials.
  </Card>

  <Card title="Go Live" icon="bullseye" href="/get-started/environments#production">
    Switch to your live API key to process real transactions.
  </Card>
</CardGroup>


# Signature Authentication
Source: https://developer.paywint.com/get-started/signature-auth

How to generate HMAC-SHA256 signatures for secure API access in Paywint.

All requests to Paywint APIs must be authenticated using an HMAC-SHA256 signature. This ensures both the integrity and authenticity of your requests.

You must include:

* `X-Platform-ID` – your API key
* `X-Signature` – generated HMAC-SHA256 signature of the request

***

## Canonical String Format

To generate a valid signature, you need to build a **canonical string** using the following format:

```txt theme={null}
METHOD + PATH + QUERY + BODY_HASH
```

### Definitions

**METHOD**: HTTP method (e.g., GET, POST, PUT)

**PATH**: API path only (e.g., /api/platform/users/create)

**QUERY**: Raw query string (e.g., ?id=123), or empty if none

**BODY\_HASH**: SHA256 hex digest of the raw request body (for POST, PUT, etc.)

### Example Input

```
Method: POST
Path: /api/platform/users/create
Query: ?isExample=true&version=1.0.5
Body:
{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "9876543210",
  "phone_country_code": "+91"
}
```

## Signature Generation Examples

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

  const method = 'POST';
  const path = '/api/platform/users/create';
  const query = '?isExample=true&version=1.0.5';
  const body = JSON.stringify({
  name: 'John Doe',
  email: 'john@example.com',
  phone: '9876543210',
  phone_country_code: '+91'
  });

  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const canonicalString = `${method}${path}${query}${bodyHash}`;

  const signature = crypto
  .createHmac('sha256', 'your_platform_secret_key')
  .update(canonicalString)
  .digest('hex');

  console.log('X-Signature:', signature);

  ```

  ```python Python theme={null}
  import hashlib
  import hmac

  method = "POST"
  path = "/api/platform/users/create"
  query = "?isExample=true&version=1.0.5"
  body = '{"name": "John Doe", "email": "john@example.com", "phone": "9876543210", "phone_country_code": "+91"}'

  body_hash = hashlib.sha256(body.encode('utf-8')).hexdigest()
  canonical_string = method + path + query + body_hash

  secret_key = b'your_platform_secret_key'
  signature = hmac.new(secret_key, canonical_string.encode('utf-8'), hashlib.sha256).hexdigest()

  print("X-Signature:", signature)

  ```

  ```go Go Lang theme={null}
  package main

  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/hex"
  	"fmt"
  )

  func main() {
  	method := "POST"
  	path := "/api/platform/users/create"
  	query := "?isExample=true&version=1.0.5"
  	body := `{"name": "John Doe", "email": "john@example.com", "phone": "9876543210", "phone_country_code": "+91"}`

  	bodyHash := sha256.Sum256([]byte(body))
  	canonical := method + path + query + hex.EncodeToString(bodyHash[:])

  	secret := []byte("your_platform_secret_key")
  	h := hmac.New(sha256.New, secret)
  	h.Write([]byte(canonical))

  	signature := hex.EncodeToString(h.Sum(nil))
  	fmt.Println("X-Signature:", signature)
  }

  ```

  ```php PHP theme={null}
  <?php
  $method = 'POST';
  $path = '/api/platform/users/create';
  $query = '?isExample=true&version=1.0.5';
  $body = json_encode([
      'name' => 'John Doe',
      'email' => 'john@example.com',
      'phone' => '9876543210',
      'phone_country_code' => '+91'
  ]);

  $bodyHash = hash('sha256', $body);
  $canonical = $method . $path . $query . $bodyHash;

  $secretKey = 'your_platform_secret_key';
  $signature = hash_hmac('sha256', $canonical, $secretKey);

  echo "X-Signature: $signature";

  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.security.MessageDigest;
  import java.util.Formatter;

  public class SignatureGenerator {
      public static void main(String[] args) throws Exception {
          String method = "POST";
          String path = "/api/platform/users/create";
          String query = "?isExample=true&version=1.0.5";
          String body = "{\"name\": \"John Doe\", \"email\": \"john@example.com\", \"phone\": \"9876543210\", \"phone_country_code\": \"+91\"}";

          MessageDigest md = MessageDigest.getInstance("SHA-256");
          byte[] bodyHashBytes = md.digest(body.getBytes("UTF-8"));
          StringBuilder bodyHash = new StringBuilder();
          for (byte b : bodyHashBytes) {
              bodyHash.append(String.format("%02x", b));
          }

          String canonical = method + path + query + bodyHash.toString();

          String secret = "your_platform_secret_key";
          SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
          Mac mac = Mac.getInstance("HmacSHA256");
          mac.init(keySpec);
          byte[] hmacBytes = mac.doFinal(canonical.getBytes("UTF-8"));

          Formatter formatter = new Formatter();
          for (byte b : hmacBytes) {
              formatter.format("%02x", b);
          }

          System.out.println("X-Signature: " + formatter.toString());
          formatter.close();
      }
  }

  ```

  ```ruby Ruby theme={null}
  require 'openssl'
  require 'json'
  require 'digest'

  method = 'POST'
  path = '/api/platform/users/create'
  query = '?isExample=true&version=1.0.5'
  body = {
    name: "John Doe",
    email: "john@example.com",
    phone: "9876543210",
    phone_country_code: "+91"
  }.to_json

  body_hash = Digest::SHA256.hexdigest(body)
  canonical = method + path + query + body_hash

  secret = 'your_platform_secret_key'
  signature = OpenSSL::HMAC.hexdigest("SHA256", secret, canonical)

  puts "X-Signature: #{signature}"


  ```
</CodeGroup>

## Complete API Call Examples

Once the signature is generated, use it in the X-Signature header as shown below:

<CodeGroup>
  ```curl Curl theme={null}
  curl -X POST "https://<environment>/api/platform/users/create?isExample=true&version=1.0.5" \
    -H "Content-Type: application/json" \
    -H "X-Platform-ID: YOUR_API_KEY" \
    -H "X-Signature: GENERATED_SIGNATURE" \
    -d '{
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "9876543210",
      "phone_country_code": "+91"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');
  const crypto = require('crypto');

  const apiKey = 'YOUR_API_KEY';
  const secretKey = 'your_platform_secret_key';
  const apiPath = '/api/platform/users/create';
  const query = '?isExample=true&version=1.0.5';
  const url = 'https://<environment>' + apiPath;

  const body = {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '9876543210',
    phone_country_code: '+91'
  };

  const method = 'POST';
  const bodyHash = crypto.createHash('sha256').update(JSON.stringify(body)).digest('hex');
  const canonical = method + apiPath + query + bodyHash;

  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(canonical)
    .digest('hex');

  axios.post(url, body, {
    headers: {
      'Content-Type': 'application/json',
      'X-Platform-ID': apiKey,
      'X-Signature': signature
    }
  })
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err.message));

  ```

  ```python Python theme={null}
  import hashlib
  import hmac
  import requests
  import json

  api_key = 'YOUR_API_KEY'
  secret_key = b'your_platform_secret_key'
  api_path = '/api/platform/users/create'
  query = '?isExample=true&version=1.0.5'
  url = 'https://<environment>' + api_path

  body = {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "9876543210",
      "phone_country_code": "+91"
  }
  body_str = json.dumps(body)
  body_hash = hashlib.sha256(body_str.encode()).hexdigest()
  canonical = 'POST' + api_path + query + body_hash

  signature = hmac.new(secret_key, canonical.encode(), hashlib.sha256).hexdigest()

  headers = {
      'Content-Type': 'application/json',
      'X-Platform-ID': api_key,
      'X-Signature': signature
  }

  response = requests.post(url, data=body_str, headers=headers)
  print(response.status_code, response.text)

  ```

  ```go Go Lang theme={null}
  package main

  import (
  	"bytes"
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/hex"
  	"fmt"
  	"io/ioutil"
  	"net/http"
  )

  func main() {
  	apiKey := "YOUR_API_KEY"
  	secretKey := "your_platform_secret_key"
  	apiPath := "/api/platform/users/create"
  	query := "?isExample=true&version=1.0.5"
  	url := "https://<environment>" + apiPath

  	body := `{"name":"John Doe","email":"john@example.com","phone":"9876543210","phone_country_code":"+91"}`
  	bodyHash := sha256.Sum256([]byte(body))
  	canonical := "POST" + apiPath + query + hex.EncodeToString(bodyHash[:])

  	h := hmac.New(sha256.New, []byte(secretKey))
  	h.Write([]byte(canonical))
  	signature := hex.EncodeToString(h.Sum(nil))

  	req, err := http.NewRequest("POST", url, bytes.NewBuffer([]byte(body)))
  	if err != nil {
  		panic(err)
  	}
  	req.Header.Set("Content-Type", "application/json")
  	req.Header.Set("X-Platform-ID", apiKey)
  	req.Header.Set("X-Signature", signature)

  	client := &http.Client{}
  	resp, err := client.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	respBody, _ := ioutil.ReadAll(resp.Body)
  	fmt.Println("Status:", resp.Status)
  	fmt.Println("Response:", string(respBody))
  }

  ```

  ```php PHP theme={null}
  <?php
  $apiKey = 'YOUR_API_KEY';
  $secretKey = 'your_platform_secret_key';
  $apiPath = '/api/platform/users/create';
  $query = '?isExample=true&version=1.0.5';
  $url = 'https://<environment>' . $apiPath;

  $body = json_encode([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'phone' => '9876543210',
    'phone_country_code' => '+91'
  ]);

  $bodyHash = hash('sha256', $body);
  $canonical = 'POST' . $apiPath . $query . $bodyHash;
  $signature = hash_hmac('sha256', $canonical, $secretKey);

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Platform-ID: ' . $apiKey,
    'X-Signature: ' . $signature
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  if ($response === false) {
    echo 'Curl error: ' . curl_error($ch);
  } else {
    echo 'Response: ' . $response;
  }
  curl_close($ch);

  ```

  ```java Java theme={null}
  import java.io.*;
  import java.net.*;
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.security.MessageDigest;

  public class PaywintAPI {
      public static void main(String[] args) throws Exception {
          String apiKey = "YOUR_API_KEY";
          String secretKey = "your_platform_secret_key";
          String apiPath = "/api/platform/users/create";
          String query = "?isExample=true&version=1.0.5";
          String url = "https://<environment>" + apiPath;

          String body = "{\"name\": \"John Doe\", \"email\": \"john@example.com\", \"phone\": \"9876543210\", \"phone_country_code\": \"+91\"}";

          MessageDigest md = MessageDigest.getInstance("SHA-256");
          byte[] hash = md.digest(body.getBytes("UTF-8"));
          StringBuilder bodyHash = new StringBuilder();
          for (byte b : hash) bodyHash.append(String.format("%02x", b));
          String canonical = "POST" + apiPath + query + bodyHash.toString();

          Mac mac = Mac.getInstance("HmacSHA256");
          mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
          byte[] hmac = mac.doFinal(canonical.getBytes("UTF-8"));
          StringBuilder signature = new StringBuilder();
          for (byte b : hmac) signature.append(String.format("%02x", b));

          HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
          conn.setRequestMethod("POST");
          conn.setDoOutput(true);
          conn.setRequestProperty("Content-Type", "application/json");
          conn.setRequestProperty("X-Platform-ID", apiKey);
          conn.setRequestProperty("X-Signature", signature.toString());

          try (OutputStream os = conn.getOutputStream()) {
              os.write(body.getBytes("UTF-8"));
          }

          BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream()));
          String line;
          while ((line = br.readLine()) != null) System.out.println(line);
      }
  }

  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'json'
  require 'openssl'
  require 'digest'

  api_key = 'YOUR_API_KEY'
  secret_key = 'your_platform_secret_key'
  api_path = '/api/platform/users/create'
  query = '?isExample=true&version=1.0.5'
  url = URI("https://<environment>#{api_path}")

  body = {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '9876543210',
    phone_country_code: '+91'
  }.to_json

  body_hash = Digest::SHA256.hexdigest(body)
  canonical = "POST" + api_path + query + body_hash

  signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, canonical)

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request['Content-Type'] = 'application/json'
  request['X-Platform-ID'] = api_key
  request['X-Signature'] = signature
  request.body = body

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"

  ```
</CodeGroup>

<Note>
  Alternatively, you can use the static signature in the [sandbox environment](/environments#sandbox): `8b3cb99a4b8e24fc7e01d0db635e2e47b80818144fe51400c6c6ae3ecbc84f47`
</Note>

## Best Practices

* Keep your **API Key** and **Secret Key** secure — never expose them on the client side
* Always use HTTPS to protect the signature and payload
* Regenerate the signature for every request; it's not reusable

***

Need help? Reach out to [support@paywint.com](mailto:support@paywint.com)


# Basic URL Requirements
Source: https://developer.paywint.com/guidelines/url-standards/basic-requirements

Core rules every document URL must follow before being submitted to Paywint APIs.

## Overview

All document URLs submitted to Paywint—such as for KYC/KYB verification—must follow strict security and format rules. These requirements ensure the file can be safely downloaded, scanned, and processed by our systems.

***

## Required Standards

Every URL must satisfy **all** of the following:

### **1. HTTPS Only**

URLs must use secure HTTPS protocol.

```

[https://example.com/file.pdf](https://example.com/file.pdf)   ✔ Allowed
[http://example.com/file.pdf](http://example.com/file.pdf)    ✖ Rejected

```

***

### **2. Publicly Accessible**

The document must be accessible **without authentication**, cookies, or login screens.

* No temporary session URLs
* No dashboard pages
* No signed URLs that expire in seconds (unless still accessible during upload)

***

### **3. Direct File Link**

The URL must point directly to the actual **file**, not a webpage or preview viewer.

```

[https://storage.com/docs/id-proof.png](https://storage.com/docs/id-proof.png)       ✔ Direct file
[https://drive.google.com/file/d/123/view](https://drive.google.com/file/d/123/view)    ✖ Preview page

```

***

### **4. Valid URL Format**

URLs must be properly formatted, parseable, and under **2,048 characters**.

Avoid:

* Spaces in URLs
* Misencoded characters
* Query parameters that don’t resolve to a file

***

### **5. Stable Hosting**

The URL should remain available long enough for processing.\
Paywint downloads the file once during validation, so the URL must not:

* Expire immediately
* Rotate tokens unexpectedly
* Redirect excessively

***

## Valid Example

```

[https://secure-docs.example.com/business-license.pdf](https://secure-docs.example.com/business-license.pdf)

```

## Invalid Examples

```

[http://example.com/file.pdf](http://example.com/file.pdf)                 (not HTTPS)
[https://example.com/view?file=doc.pdf](https://example.com/view?file=doc.pdf)       (not a direct link)
[https://private-server.local/doc.png](https://private-server.local/doc.png)        (private/internal network)

```

***

## Summary Checklist

Before submitting a URL, ensure it:

* Uses **HTTPS**
* Is **publicly reachable**
* Links **directly to the file**
* Points to a **supported file type**
* Is **properly formatted**
* Is **stable and valid** at request time


# Cloud Storage Guidelines
Source: https://developer.paywint.com/guidelines/url-standards/cloud-storage

How to correctly generate direct-access URLs from popular cloud storage services.

## Overview

When submitting documents from cloud storage services such as Google Drive, Dropbox, AWS S3, or others, you **must provide a direct download link**.\
Preview links, share pages, and redirect-based URLs will fail validation.

This guide explains how to generate valid, secure, and properly formatted direct URLs for each supported provider.

***

## General Rules for Cloud Storage

Regardless of provider, all URLs must:

* Use **HTTPS**
* Be **publicly accessible**
* Be a **direct file URL**
* Resolve to a supported file type (PDF, JPEG, PNG, DOCX, etc.)

***

## Google Drive

Google Drive shares files using a *viewer URL*, which is **not** accepted.\
You must convert it into a **direct download URL**.

### Step-by-Step

1. Right-click file → **Get link**
2. Change permissions to **“Anyone with the link”**
3. Extract the file ID from the sharing link\
   Example viewer URL:

```

[https://drive.google.com/file/d/1ABC123def456/view](https://drive.google.com/file/d/1ABC123def456/view)

```

4. Convert to a **direct download URL**:

```

[https://drive.google.com/uc?export=download&id=1ABC123def456](https://drive.google.com/uc?export=download&id=1ABC123def456)

```

### Valid Google Drive URL

```

[https://drive.google.com/uc?export=download&id=1ABC123def456](https://drive.google.com/uc?export=download&id=1ABC123def456)

```

***

## Dropbox

Dropbox share links are preview links and must be transformed.

### Step-by-Step

1. Create a shared link
2. Replace `dl=0` with `dl=1`

### Example

Original link (invalid):

```

[https://www.dropbox.com/s/abc12345xyz/document.pdf?dl=0](https://www.dropbox.com/s/abc12345xyz/document.pdf?dl=0)

```

Direct download link (valid):

```

[https://www.dropbox.com/s/abc12345xyz/document.pdf?dl=1](https://www.dropbox.com/s/abc12345xyz/document.pdf?dl=1)

```

***

## AWS S3

AWS S3 supports direct file URLs when the object is public.

### Step-by-Step

1. Upload file to your S3 bucket
2. Make sure the object is set to **public read**
3. Use the S3 file link:

```

[https://bucket-name.s3.region.amazonaws.com/path/to/file.pdf](https://bucket-name.s3.region.amazonaws.com/path/to/file.pdf)

```

### Example

```

[https://my-docs.s3.us-east-1.amazonaws.com/licensing/certificate.pdf](https://my-docs.s3.us-east-1.amazonaws.com/licensing/certificate.pdf)

```

**Note:**\
If using **pre-signed URLs**, ensure they remain valid until Paywint processes the file.\
URLs that expire immediately may fail.

***

## Google Cloud Storage (GCS)

### Step-by-Step

1. Upload file to a bucket
2. Ensure public access for the object
3. Use the public URL format:

```

[https://storage.googleapis.com/BUCKET_NAME/FILE_NAME](https://storage.googleapis.com/BUCKET_NAME/FILE_NAME)

```

### Example

```

[https://storage.googleapis.com/company-docs/proof-of-address.png](https://storage.googleapis.com/company-docs/proof-of-address.png)

```

***

## OneDrive / SharePoint

These services often generate **redirected or preview links**, which fail validation.\
To use them:

* Must generate a **direct download link**
* Ensure anonymous access is allowed

### Example Conversion

Viewer URL:

```

[https://onedrive.live.com/?cid=123&id=ABC12345ABC12345%21123](https://onedrive.live.com/?cid=123&id=ABC12345ABC12345%21123)

```

Direct download format:

```

[https://onedrive.live.com/download?cid=123&id=ABC12345ABC12345%21123](https://onedrive.live.com/download?cid=123&id=ABC12345ABC12345%21123)

```

***

## iCloud Drive (Not Recommended)

iCloud links commonly:

* Expire quickly
* Require additional authentication
* Use redirect-based links

Because of these limitations, avoid using iCloud for document submission.

***

## Summary

| Provider              | Supported | Direct Link Required | Notes                                |
| --------------------- | --------- | -------------------- | ------------------------------------ |
| Google Drive          | ✔         | ✔                    | Must use `uc?export=download` format |
| Dropbox               | ✔         | ✔                    | Convert `dl=0` → `dl=1`              |
| AWS S3                | ✔         | ✔                    | Public or stable pre-signed required |
| Google Cloud Storage  | ✔         | ✔                    | Public file required                 |
| OneDrive / SharePoint | ✔         | ✔                    | Preview links rejected               |
| iCloud                | ✖         | N/A                  | Not reliable for validation          |

***

## Best Practices

* Always test the URL in an incognito browser session
* Avoid URLs that expire in less than **10 minutes**
* Prefer reliable cloud providers such as AWS S3 or Google Cloud Storage
* Keep file names clean and simple: `certificate.pdf`, `id-front.jpg`, etc.


# Valid & Invalid URL Examples
Source: https://developer.paywint.com/guidelines/url-standards/examples

Examples of URLs that pass and fail Paywint's URL validation checks.

## Overview

This page provides clear examples of URLs that **meet** Paywint’s requirements, and those that will be **rejected** during validation. Use these examples as a reference when generating or verifying document URLs.

***

## Valid URL Examples

These URLs use HTTPS, point directly to downloadable files, and meet all security and accessibility requirements:

```

[https://cdn.example.com/docs/business-license.pdf](https://cdn.example.com/docs/business-license.pdf)
[https://secure-storage.mycompany.com/uploads/id-proof.png](https://secure-storage.mycompany.com/uploads/id-proof.png)
[https://drive.google.com/uc?export=download&id=1ABC123xyz](https://drive.google.com/uc?export=download&id=1ABC123xyz)
[https://bucket-name.s3.us-west-1.amazonaws.com/registration-document.jpg](https://bucket-name.s3.us-west-1.amazonaws.com/registration-document.jpg)
[https://assets.examplecdn.com/files/proof-of-address.jpeg](https://assets.examplecdn.com/files/proof-of-address.jpeg)

```

***

## Invalid URL Examples

The following URLs fail validation due to security issues, unsupported formats, private networks, or non-direct links:

```

[http://example.com/document.pdf](http://example.com/document.pdf)                     (not HTTPS)
[https://192.168.1.10/file.pdf](https://192.168.1.10/file.pdf)                       (private IP address)
[https://localhost:5000/file.pdf](https://localhost:5000/file.pdf)                      (localhost)
ftp://files.example.com/document.pdf                 (unsupported protocol)
[https://drive.google.com/file/d/12345/view](https://drive.google.com/file/d/12345/view)           (preview link, not direct download)
[https://example.com/files/large-document-12mb.pdf](https://example.com/files/large-document-12mb.pdf)    (exceeds 7 MB size limit)
[https://myapp.internal.company/documents/id.pdf](https://myapp.internal.company/documents/id.pdf)      (internal network resource)

```

***

## Quick Tips

* Always test URLs in an **incognito browser** — if it requires login, it will fail validation.
* Avoid preview/share pages from cloud storage.
* Direct links **must** end with a file extension (e.g., `.pdf`, `.jpg`, `.png`).
* Ensure the file is publicly reachable via HTTPS.


# File Requirements
Source: https://developer.paywint.com/guidelines/url-standards/file-rules

File size, type, and validation rules for uploaded documents.

## Requirements

### File Size

Maximum allowed file size: **7 MB**

### Download Timeout

All files must be downloadable within **10 seconds**.

***

## Supported File Types

Depending on the API, supported formats include:

### Documents

* PDF
* DOCX
* DOC
* TXT

### Images

* JPG / JPEG
* PNG
* GIF

<Note>
  Always check the API-specific documentation to confirm supported formats.
</Note>

***

## Validation Process

When you submit a URL, Paywint performs these checks:

1. **Syntax & length validation**
2. **Security rule checks**
3. **DNS resolution**
4. **Public IP validation**
5. **File download test**
6. **Content type & size verification**

A URL is accepted only if all checks pass.


# URL Standards Overview
Source: https://developer.paywint.com/guidelines/url-standards/overview

Overview of URL requirements and validation rules for submitting documents through the Paywint API.

## Overview

Some Paywint API endpoints—such as KYB verification, document submission, and compliance checks—require you to provide direct URLs to documents.\
These URLs must follow specific standards to ensure they are secure, accessible, and valid for automated processing.

This section outlines all requirements for document URLs, including security rules, file guidelines, storage recommendations, and troubleshooting steps.

***

## What This Section Covers

<CardGroup>
  <Card title="Basic Requirements" href="/guidelines/url-standards/basic-requirements" icon="check-circle">
    Core rules every document URL must follow, including HTTPS and accessibility.
  </Card>

  <Card title="Security Rules" href="/guidelines/url-standards/security-rules" icon="shield-check">
    Allowed protocols, network restrictions, and security validations applied.
  </Card>

  <Card title="File Requirements" href="/guidelines/url-standards/file-rules" icon="file-check">
    Supported file types, maximum file size, and download behavior.
  </Card>

  <Card title="Cloud Storage Guidelines" href="/guidelines/url-standards/cloud-storage" icon="cloud">
    How to generate direct download URLs from Google Drive, Dropbox, AWS S3, and more.
  </Card>

  <Card title="Troubleshooting" href="/guidelines/url-standards/troubleshooting" icon="cog">
    Common errors, causes, and recommended fixes.
  </Card>

  <Card title="Examples" href="/guidelines/url-standards/examples" icon="list">
    Valid and invalid URL examples for quick reference.
  </Card>
</CardGroup>

***

## Why URL Standards Matter

Paywint validates each document URL to ensure:

* The file is safe and accessible
* The host is publicly reachable
* The URL resolves correctly
* The content meets size and type requirements

Following these guidelines prevents delays in verification and ensures smooth document processing.

***

## When You Need These Guidelines

These URL rules apply whenever you submit a document through Paywint, including:

* KYB verification
* Uploading compliance documentation
* Business identity verification
* Proof-of-address checks
* Any endpoint that accepts a document URL

For API-specific requirements, refer to the corresponding endpoint documentation.

***

## Next Steps

Choose a section to continue:

* Start with **[Basic Requirements](/guidelines/url-standards/basic-requirements)**
* Or explore the entire URL Standards collection using the left sidebar navigation


# Security Rules
Source: https://developer.paywint.com/guidelines/url-standards/security-rules

Security restrictions for document URLs.

## Allowed Protocols

Only secure **HTTPS** URLs are supported.

Blocked schemes include:

* `http://`
* `file://`
* `ftp://`
* `javascript://`
* `data://`

***

## Network Restrictions

URLs cannot resolve to:

* Private IP ranges (e.g., `192.168.x.x`, `10.x.x.x`)
* `localhost` or `127.0.0.1`
* Internal corporate servers
* Non-public networks
* Administrative service ports

Paywint must be able to access the file over the public internet.

***

## Why These Restrictions Exist

These rules prevent:

* Exposure of internal systems
* Security vulnerabilities
* Attempts to bypass public hosting
* API failures due to inaccessible resources


# Troubleshooting URL Issues
Source: https://developer.paywint.com/guidelines/url-standards/troubleshooting

Common URL validation errors and how to fix them.

## Common Issues & Fixes

<AccordionGroup>
  <Accordion title="URL uses blocked scheme">
    **Problem:** URL doesn't use HTTPS\
    **Fix:** Change `http://` to `https://`
  </Accordion>

  <Accordion title="URL resolves to private IP">
    **Problem:** URL points to internal network\
    **Fix:** Use a public hosting provider or cloud storage
  </Accordion>

  <Accordion title="File exceeds maximum size">
    **Problem:** File > 7 MB\
    **Fix:** Compress or re-export as optimized PDF
  </Accordion>

  <Accordion title="Unsupported file type">
    **Problem:** File extension not supported\
    **Fix:** Convert to PDF, DOCX, JPG, or PNG
  </Accordion>

  <Accordion title="Network timeout">
    **Problem:** Server fails to deliver file in 10 seconds\
    **Fix:** Use faster hosting or CDN
  </Accordion>
</AccordionGroup>


# Available Values for "entityType" and "industryType" in API Payload
Source: https://developer.paywint.com/industry-entity-available-values



To ensure proper classification of businesses when submitting **KYB (Know Your Business)** information, our API accepts specific values for both `entityType` and `industryType`. These values must be passed in the payload using the respective `id` and `mcc` codes listed below.

***

## Entity Types

Use the following `id` values to specify the type of entity during onboarding or when submitting business information:

<Tabs>
  <Tab title="Table">
    | ID      | Title                       |
    | ------- | --------------------------- |
    | `ent1`  | Corporation                 |
    | `ent2`  | Sole Proprietor             |
    | `ent3`  | Single Member LLC           |
    | `ent4`  | Limited Liability Company   |
    | `ent5`  | General Partnership         |
    | `ent6`  | Unlisted Corporation        |
    | `ent7`  | Publicly Traded Corporation |
    | `ent8`  | Association                 |
    | `ent9`  | Non Profit                  |
    | `ent10` | Government Organization     |
    | `ent11` | Revocable Trust             |
    | `ent12` | Irrevocable Trust           |
    | `ent13` | Estate                      |
  </Tab>

  <Tab title="JSON">
    ```json Entity Types theme={null}
    [
      { "id": "ent1", "title": "Corporation" },
      { "id": "ent2", "title": "Sole Proprietor" },
      { "id": "ent3", "title": "Single Member LLC" },
      { "id": "ent4", "title": "Limited Liability Company" },
      { "id": "ent5", "title": "General Partnership" },
      { "id": "ent6", "title": "Unlisted Corporation" },
      { "id": "ent7", "title": "Publicly Traded Corporation" },
      { "id": "ent8", "title": "Association" },
      { "id": "ent9", "title": "Non Profit" },
      { "id": "ent10", "title": "Government Organization" },
      { "id": "ent11", "title": "Revocable Trust" },
      { "id": "ent12", "title": "Irrevocable Trust" },
      { "id": "ent13", "title": "Estate" }
    ]
    ```
  </Tab>
</Tabs>

> **Payload Example:**

```json Payload theme={null}
{
  "entity_type": "ent4"
}
```

***

## Industry Types

Provide the `mcc` (Merchant Category Code) of the business's industry. Below is the list of supported industries and their associated MCCs:

<Tabs>
  <Tab title="Table">
    | MCC  | Industry Title                                                                                                           |
    | ---- | ------------------------------------------------------------------------------------------------------------------------ |
    | 7623 | A/C, Refrigeration Repair                                                                                                |
    | 8931 | Accounting/Bookkeeping Services                                                                                          |
    | 7311 | Advertising Services                                                                                                     |
    | 763  | Agricultural Cooperative                                                                                                 |
    | 4511 | Airlines, Air Carriers                                                                                                   |
    | 4582 | Airports, Flying Fields                                                                                                  |
    | 4119 | Ambulance Services                                                                                                       |
    | 7996 | Amusement Parks Carnivals                                                                                                |
    | 5937 | Antique Reproductions                                                                                                    |
    | 5932 | Antique Shops                                                                                                            |
    | 7998 | Aquariums                                                                                                                |
    | 8911 | Architectural Surveying Services                                                                                         |
    | 5971 | Art Dealers and Galleries                                                                                                |
    | 5970 | Artists Supply and Craft Shops                                                                                           |
    | 7531 | Auto Body Repair Shops                                                                                                   |
    | 7535 | Auto Paint Shops                                                                                                         |
    | 7538 | Auto Service Shops                                                                                                       |
    | 5531 | Auto and Home Supply Stores                                                                                              |
    | 6011 | Automated Cash Disburse                                                                                                  |
    | 5542 | Automated Fuel Dispensers                                                                                                |
    | 8675 | Automobile Associations                                                                                                  |
    | 5533 | Automotive Parts and Accessories Stores                                                                                  |
    | 5532 | Automotive Tire Stores                                                                                                   |
    | 9223 | Bail and Bond Payments                                                                                                   |
    | 5462 | Bakeries                                                                                                                 |
    | 7929 | Bands, Orchestras                                                                                                        |
    | 7230 | Barber and Beauty Shops                                                                                                  |
    | 7995 | Betting/Casino Gambling                                                                                                  |
    | 5940 | Bicycle Shops                                                                                                            |
    | 7932 | Billiard/Pool Establishments                                                                                             |
    | 5551 | Boat Dealers                                                                                                             |
    | 4457 | Boat Rentals and Leases                                                                                                  |
    | 5942 | Book Stores                                                                                                              |
    | 5192 | Books, Periodicals, and Newspapers                                                                                       |
    | 7933 | Bowling Alleys                                                                                                           |
    | 4131 | Bus Lines                                                                                                                |
    | 8244 | Business/Secretarial Schools                                                                                             |
    | 7278 | Buying/Shopping Services                                                                                                 |
    | 4899 | Cable, Satellite, and Other Pay Television and Radio                                                                     |
    | 5946 | Camera and Photographic Supply Stores                                                                                    |
    | 5441 | Candy, Nut, and Confectionery Stores                                                                                     |
    | 7512 | Car Rental Agencies                                                                                                      |
    | 7542 | Car Washes                                                                                                               |
    | 5511 | Car and Truck Dealers (New & Used) Sales, Service, Repairs Parts and Leasing                                             |
    | 5521 | Car and Truck Dealers (Used Only) Sales, Service, Repairs Parts and Leasing                                              |
    | 1750 | Carpentry Services                                                                                                       |
    | 7217 | Carpet/Upholstery Cleaning                                                                                               |
    | 5811 | Caterers                                                                                                                 |
    | 8398 | Charitable and Social Service Organizations - Fundraising                                                                |
    | 5169 | Chemicals and Allied Products (Not Elsewhere Classified)                                                                 |
    | 8351 | Child Care Services                                                                                                      |
    | 5641 | Childrens and Infants Wear Stores                                                                                        |
    | 8049 | Chiropodists, Podiatrists                                                                                                |
    | 8041 | Chiropractors                                                                                                            |
    | 5993 | Cigar Stores and Stands                                                                                                  |
    | 8641 | Civic, Social, Fraternal Associations                                                                                    |
    | 7349 | Cleaning and Maintenance                                                                                                 |
    | 7296 | Clothing Rental                                                                                                          |
    | 8220 | Colleges, Universities                                                                                                   |
    | 5046 | Commercial Equipment (Not Elsewhere Classified)                                                                          |
    | 5139 | Commercial Footwear                                                                                                      |
    | 7333 | Commercial Photography, Art and Graphics                                                                                 |
    | 4111 | Commuter Transport, Ferries                                                                                              |
    | 4816 | Computer Network Services                                                                                                |
    | 7372 | Computer Programming                                                                                                     |
    | 7379 | Computer Repair                                                                                                          |
    | 5734 | Computer Software Stores                                                                                                 |
    | 5045 | Computers, Peripherals, and Software                                                                                     |
    | 1771 | Concrete Work Services                                                                                                   |
    | 5039 | Construction Materials (Not Elsewhere Classified)                                                                        |
    | 7392 | Consulting, Public Relations                                                                                             |
    | 8241 | Correspondence Schools                                                                                                   |
    | 5977 | Cosmetic Stores                                                                                                          |
    | 7277 | Counseling Services                                                                                                      |
    | 7997 | Country Clubs                                                                                                            |
    | 4215 | Courier Services                                                                                                         |
    | 9211 | Court Costs, Including Alimony and Child Support - Courts of Law                                                         |
    | 7321 | Credit Reporting Agencies                                                                                                |
    | 4411 | Cruise Lines                                                                                                             |
    | 5451 | Dairy Products Stores                                                                                                    |
    | 7911 | Dance Hall, Studios, Schools                                                                                             |
    | 7273 | Dating/Escort Services                                                                                                   |
    | 8021 | Dentists, Orthodontists                                                                                                  |
    | 5311 | Department Stores                                                                                                        |
    | 7393 | Detective Agencies                                                                                                       |
    | 5815 | Digital Goods Media Books, Movies, Music                                                                                 |
    | 5817 | Digital Goods Applications (Excludes Games)                                                                              |
    | 5816 | Digital Goods Games                                                                                                      |
    | 5818 | Digital Goods Large Digital Goods Merchant                                                                               |
    | 5964 | Direct Marketing - Catalog Merchant                                                                                      |
    | 5965 | Direct Marketing - Combination Catalog and Retail Merchant                                                               |
    | 5967 | Direct Marketing - Inbound Telemarketing                                                                                 |
    | 5960 | Direct Marketing - Insurance Services                                                                                    |
    | 5969 | Direct Marketing - Other                                                                                                 |
    | 5966 | Direct Marketing - Outbound Telemarketing                                                                                |
    | 5968 | Direct Marketing - Subscription                                                                                          |
    | 5962 | Direct Marketing - Travel                                                                                                |
    | 5310 | Discount Stores                                                                                                          |
    | 8011 | Doctors                                                                                                                  |
    | 5963 | Door-To-Door Sales                                                                                                       |
    | 5714 | Drapery, Window Covering, and Upholstery Stores                                                                          |
    | 5813 | Drinking Places                                                                                                          |
    | 5912 | Drug Stores and Pharmacies                                                                                               |
    | 5122 | Drugs, Drug Proprietaries, and Druggist Sundries                                                                         |
    | 7216 | Dry Cleaners                                                                                                             |
    | 5099 | Durable Goods (Not Elsewhere Classified)                                                                                 |
    | 5309 | Duty Free Stores                                                                                                         |
    | 5812 | Eating Places, Restaurants                                                                                               |
    | 8299 | Educational Services                                                                                                     |
    | 5997 | Electric Razor Stores                                                                                                    |
    | 5552 | Electric Vehicle Charging                                                                                                |
    | 5065 | Electrical Parts and Equipment                                                                                           |
    | 1731 | Electrical Services                                                                                                      |
    | 7622 | Electronics Repair Shops                                                                                                 |
    | 5732 | Electronics Stores                                                                                                       |
    | 8211 | Elementary, Secondary Schools                                                                                            |
    | 9702 | Emergency Services (GCAS) (Visa use only)                                                                                |
    | 7361 | Employment/Temp Agencies                                                                                                 |
    | 7394 | Equipment Rental                                                                                                         |
    | 7342 | Exterminating Services                                                                                                   |
    | 5651 | Family Clothing Stores                                                                                                   |
    | 5814 | Fast Food Restaurants                                                                                                    |
    | 6012 | Financial Institutions                                                                                                   |
    | 9222 | Fines - Government Administrative Entities                                                                               |
    | 5718 | Fireplace, Fireplace Screens, and Accessories Stores                                                                     |
    | 5713 | Floor Covering Stores                                                                                                    |
    | 5992 | Florists                                                                                                                 |
    | 5193 | Florists Supplies, Nursery Stock, and Flowers                                                                            |
    | 5422 | Freezer and Locker Meat Provisioners                                                                                     |
    | 5983 | Fuel Dealers (Non Automotive)                                                                                            |
    | 7261 | Funeral Services, Crematories                                                                                            |
    | 7641 | Furniture Repair, Refinishing                                                                                            |
    | 5712 | Furniture, Home Furnishings, and Equipment Stores, Except Appliances                                                     |
    | 5681 | Furriers and Fur Shops                                                                                                   |
    | 1520 | General Services                                                                                                         |
    | 5947 | Gift, Card, Novelty, and Souvenir Shops                                                                                  |
    | 5231 | Glass, Paint, and Wallpaper Stores                                                                                       |
    | 5950 | Glassware, Crystal Stores                                                                                                |
    | 7992 | Golf Courses - Public                                                                                                    |
    | 7801 | Government Licensed On-line Casinos (On-Line Gambling)(US Region only)                                                   |
    | 9399 | Government Services (Not Elsewhere Classified)                                                                           |
    | 7802 | Government-Licensed Horse/Dog Racing (US Region only)                                                                    |
    | 9406 | Government-Owned Lotteries (Non-US region)                                                                               |
    | 7800 | Government-Owned Lotteries (US Region only)                                                                              |
    | 5411 | Grocery Stores, Supermarkets                                                                                             |
    | 5251 | Hardware Stores                                                                                                          |
    | 5072 | Hardware, Equipment, and Supplies                                                                                        |
    | 7298 | Health and Beauty Spas                                                                                                   |
    | 5975 | Hearing Aids Sales and Supplies                                                                                          |
    | 1711 | Heating, Plumbing, A/C                                                                                                   |
    | 5945 | Hobby, Toy, and Game Shops                                                                                               |
    | 5200 | Home Supply Warehouse Stores                                                                                             |
    | 8062 | Hospitals                                                                                                                |
    | 7011 | Hotels, Motels, and Resorts                                                                                              |
    | 5722 | Household Appliance Stores                                                                                               |
    | 5085 | Industrial Supplies (Not Elsewhere Classified)                                                                           |
    | 7375 | Information Retrieval Services                                                                                           |
    | 6399 | Insurance - Default                                                                                                      |
    | 6300 | Insurance Underwriting, Premiums                                                                                         |
    | 9950 | Intra-Company Purchases                                                                                                  |
    | 5944 | Jewelry Stores, Watches, Clocks, and Silverware Stores                                                                   |
    | 780  | Landscaping Services                                                                                                     |
    | 7211 | Laundries                                                                                                                |
    | 7210 | Laundry, Cleaning Services                                                                                               |
    | 8111 | Legal Services, Attorneys                                                                                                |
    | 5948 | Luggage and Leather Goods Stores                                                                                         |
    | 5211 | Lumber, Building Materials Stores                                                                                        |
    | 6010 | Manual Cash Disburse                                                                                                     |
    | 4468 | Marinas, Service and Supplies                                                                                            |
    | 5262 | Marketplaces                                                                                                             |
    | 1740 | Masonry, Stonework, and Plaster                                                                                          |
    | 7297 | Massage Parlors                                                                                                          |
    | 8099 | Medical Services                                                                                                         |
    | 8071 | Medical and Dental Labs                                                                                                  |
    | 5047 | Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies                                                         |
    | 8699 | Membership Organizations                                                                                                 |
    | 5611 | Mens and Boys Clothing and Accessories Stores                                                                            |
    | 5691 | Mens, Women's Clothing Stores                                                                                            |
    | 5051 | Metal Service Centers                                                                                                    |
    | 5699 | Miscellaneous Apparel and Accessory Shops                                                                                |
    | 5599 | Miscellaneous Auto Dealers                                                                                               |
    | 7399 | Miscellaneous Business Services                                                                                          |
    | 5499 | Miscellaneous Food Stores - Convenience Stores and Specialty Markets                                                     |
    | 5399 | Miscellaneous General Merchandise                                                                                        |
    | 7299 | Miscellaneous General Services                                                                                           |
    | 5719 | Miscellaneous Home Furnishing Specialty Stores                                                                           |
    | 2741 | Miscellaneous Publishing and Printing                                                                                    |
    | 7999 | Miscellaneous Recreation Services                                                                                        |
    | 7699 | Miscellaneous Repair Shops                                                                                               |
    | 5999 | Miscellaneous Specialty Retail                                                                                           |
    | 5271 | Mobile Home Dealers                                                                                                      |
    | 7832 | Motion Picture Theaters                                                                                                  |
    | 4214 | Motor Freight Carriers and Trucking - Local and Long Distance, Moving and Storage Companies, and Local Delivery Services |
    | 5592 | Motor Homes Dealers                                                                                                      |
    | 5013 | Motor Vehicle Supplies and New Parts                                                                                     |
    | 5571 | Motorcycle Shops and Dealers                                                                                             |
    | 5561 | Motorcycle Shops, Dealers                                                                                                |
    | 5733 | Music Stores-Musical Instruments, Pianos, and Sheet Music                                                                |
    | 5994 | News Dealers and Newsstands                                                                                              |
    | 6051 | Non-FI, Money Orders                                                                                                     |
    | 6540 | Non-FI, Stored Value Card Purchase/Load                                                                                  |
    | 5199 | Nondurable Goods (Not Elsewhere Classified)                                                                              |
    | 5261 | Nurseries, Lawn and Garden Supply Stores                                                                                 |
    | 8050 | Nursing/Personal Care                                                                                                    |
    | 5021 | Office and Commercial Furniture                                                                                          |
    | 8043 | Opticians, Eyeglasses                                                                                                    |
    | 8042 | Optometrists, Ophthalmologist                                                                                            |
    | 5976 | Orthopedic Goods - Prosthetic Devices                                                                                    |
    | 8031 | Osteopaths                                                                                                               |
    | 5921 | Package Stores-Beer, Wine, and Liquor                                                                                    |
    | 5198 | Paints, Varnishes, and Supplies                                                                                          |
    | 7523 | Parking Lots, Garages                                                                                                    |
    | 4112 | Passenger Railways                                                                                                       |
    | 5933 | Pawn Shops                                                                                                               |
    | 5995 | Pet Shops, Pet Food, and Supplies                                                                                        |
    | 5172 | Petroleum and Petroleum Products                                                                                         |
    | 7395 | Photo Developing                                                                                                         |
    | 7221 | Photographic Studios                                                                                                     |
    | 5044 | Photographic, Photocopy, Microfilm Equipment, and Supplies                                                               |
    | 7829 | Picture/Video Production                                                                                                 |
    | 5131 | Piece Goods, Notions, and Other Dry Goods                                                                                |
    | 5074 | Plumbing, Heating Equipment, and Supplies                                                                                |
    | 8651 | Political Organizations                                                                                                  |
    | 9402 | Postal Services - Government Only                                                                                        |
    | 5094 | Precious Stones and Metals, Watches and Jewelry                                                                          |
    | 8999 | Professional Services                                                                                                    |
    | 4225 | Public Warehousing and Storage - Farm Products, Refrigerated Goods, Household Goods, and Storage                         |
    | 7338 | Quick Copy, Repro, and Blueprint                                                                                         |
    | 4011 | Railroads                                                                                                                |
    | 6513 | Real Estate Agents and Managers - Rentals                                                                                |
    | 5735 | Record Stores                                                                                                            |
    | 7519 | Recreational Vehicle Rentals                                                                                             |
    | 5973 | Religious Goods Stores                                                                                                   |
    | 8661 | Religious Organizations                                                                                                  |
    | 1761 | Roofing/Siding, Sheet Metal                                                                                              |
    | 7339 | Secretarial Support Services                                                                                             |
    | 6211 | Security Brokers/Dealers                                                                                                 |
    | 5541 | Service Stations                                                                                                         |
    | 5949 | Sewing, Needlework, Fabric, and Piece Goods Stores                                                                       |
    | 7251 | Shoe Repair/Hat Cleaning                                                                                                 |
    | 5661 | Shoe Stores                                                                                                              |
    | 7629 | Small Appliance Repair                                                                                                   |
    | 5598 | Snowmobile Dealers                                                                                                       |
    | 1799 | Special Trade Services                                                                                                   |
    | 2842 | Specialty Cleaning                                                                                                       |
    | 5941 | Sporting Goods Stores                                                                                                    |
    | 7032 | Sporting/Recreation Camps                                                                                                |
    | 7941 | Sports Clubs/Fields                                                                                                      |
    | 5655 | Sports and Riding Apparel Stores                                                                                         |
    | 5972 | Stamp and Coin Stores                                                                                                    |
    | 5111 | Stationary, Office Supplies, Printing and Writing Paper                                                                  |
    | 5943 | Stationery Stores, Office, and School Supply Stores                                                                      |
    | 5996 | Swimming Pools Sales                                                                                                     |
    | 4723 | TUI Travel - Germany                                                                                                     |
    | 5697 | Tailors, Alterations                                                                                                     |
    | 9311 | Tax Payments - Government Agencies                                                                                       |
    | 7276 | Tax Preparation Services                                                                                                 |
    | 4121 | Taxicabs/Limousines                                                                                                      |
    | 4812 | Telecommunication Equipment and Telephone Sales                                                                          |
    | 4814 | Telecommunication Services                                                                                               |
    | 4821 | Telegraph Services                                                                                                       |
    | 5998 | Tent and Awning Shops                                                                                                    |
    | 8734 | Testing Laboratories                                                                                                     |
    | 7922 | Theatrical Ticket Agencies                                                                                               |
    | 7012 | Timeshares                                                                                                               |
    | 7534 | Tire Retreading and Repair                                                                                               |
    | 4784 | Tolls/Bridge Fees                                                                                                        |
    | 7991 | Tourist Attractions and Exhibits                                                                                         |
    | 7549 | Towing Services                                                                                                          |
    | 7033 | Trailer Parks, Campgrounds                                                                                               |
    | 4789 | Transportation Services (Not Elsewhere Classified)                                                                       |
    | 4722 | Travel Agencies, Tour Operators                                                                                          |
    | 7513 | Truck/Utility Trailer Rentals                                                                                            |
    | 2791 | Typesetting, Plate Making, and Related Services                                                                          |
    | 5978 | Typewriter Stores                                                                                                        |
    | 9405 | U.S. Federal Government Agencies or Departments                                                                          |
    | 5137 | Uniforms, Commercial Clothing                                                                                            |
    | 5931 | Used Merchandise and Secondhand Stores                                                                                   |
    | 4900 | Utilities                                                                                                                |
    | 5331 | Variety Stores                                                                                                           |
    | 742  | Veterinary Services                                                                                                      |
    | 7993 | Video Amusement Game Supplies                                                                                            |
    | 7994 | Video Game Arcades                                                                                                       |
    | 7841 | Video Tape Rental Stores                                                                                                 |
    | 8249 | Vocational/Trade Schools                                                                                                 |
    | 7631 | Watch/Jewelry Repair                                                                                                     |
    | 7692 | Welding Repair                                                                                                           |
    | 5300 | Wholesale Clubs                                                                                                          |
    | 5698 | Wig and Toupee Stores                                                                                                    |
    | 4829 | Wires, Money Orders                                                                                                      |
    | 5631 | women's Accessory and Specialty Shops                                                                                    |
    | 5621 | women's Ready-To-Wear Stores                                                                                             |
    | 5935 | Wrecking and Salvage Yards                                                                                               |
  </Tab>

  <Tab title="JSON">
    ```json Industry Types theme={null}
    [
        {"industry_type": "A/C, Refrigeration Repair", "mcc": 7623},
        {"industry_type": "Accounting/Bookkeeping Services", "mcc": 8931},
        {"industry_type": "Advertising Services", "mcc": 7311},
        {"industry_type": "Agricultural Cooperative", "mcc": 763},
        {"industry_type": "Airlines, Air Carriers", "mcc": 4511},
        {"industry_type": "Airports, Flying Fields", "mcc": 4582},
        {"industry_type": "Ambulance Services", "mcc": 4119},
        {"industry_type": "Amusement Parks Carnivals", "mcc": 7996},
        {"industry_type": "Antique Reproductions", "mcc": 5937},
        {"industry_type": "Antique Shops", "mcc": 5932},
        {"industry_type": "Aquariums", "mcc": 7998},
        {"industry_type": "Architectural Surveying Services", "mcc": 8911},
        {"industry_type": "Art Dealers and Galleries", "mcc": 5971},
        {"industry_type": "Artists Supply and Craft Shops", "mcc": 5970},
        {"industry_type": "Auto Body Repair Shops", "mcc": 7531},
        {"industry_type": "Auto Paint Shops", "mcc": 7535},
        {"industry_type": "Auto Service Shops", "mcc": 7538},
        {"industry_type": "Auto and Home Supply Stores", "mcc": 5531},
        {"industry_type": "Automated Cash Disburse", "mcc": 6011},
        {"industry_type": "Automated Fuel Dispensers", "mcc": 5542},
        {"industry_type": "Automobile Associations", "mcc": 8675},
        {"industry_type": "Automotive Parts and Accessories Stores", "mcc": 5533},
        {"industry_type": "Automotive Tire Stores", "mcc": 5532},
        {"industry_type": "Bail and Bond Payments ", "mcc": 9223},
        {"industry_type": "Bakeries", "mcc": 5462},
        {"industry_type": "Bands, Orchestras", "mcc": 7929},
        {"industry_type": "Barber and Beauty Shops", "mcc": 7230},
        {"industry_type": "Betting/Casino Gambling", "mcc": 7995},
        {"industry_type": "Bicycle Shops", "mcc": 5940},
        {"industry_type": "Billiard/Pool Establishments", "mcc": 7932},
        {"industry_type": "Boat Dealers", "mcc": 5551},
        {"industry_type": "Boat Rentals and Leases", "mcc": 4457},
        {"industry_type": "Book Stores", "mcc": 5942},
        {"industry_type": "Books, Periodicals, and Newspapers", "mcc": 5192},
        {"industry_type": "Bowling Alleys", "mcc": 7933},
        {"industry_type": "Bus Lines", "mcc": 4131},
        {"industry_type": "Business/Secretarial Schools", "mcc": 8244},
        {"industry_type": "Buying/Shopping Services", "mcc": 7278},
        {"industry_type": "Cable, Satellite, and Other Pay Television and Radio", "mcc": 4899},
        {"industry_type": "Camera and Photographic Supply Stores", "mcc": 5946},
        {"industry_type": "Candy, Nut, and Confectionery Stores", "mcc": 5441},
        {"industry_type": "Car Rental Agencies", "mcc": 7512},
        {"industry_type": "Car Washes", "mcc": 7542},
        {"industry_type": "Car and Truck Dealers (New & Used) Sales, Service, Repairs Parts and Leasing", "mcc": 5511},
        {"industry_type": "Car and Truck Dealers (Used Only) Sales, Service, Repairs Parts and Leasing", "mcc": 5521},
        {"industry_type": "Carpentry Services", "mcc": 1750},
        {"industry_type": "Carpet/Upholstery Cleaning", "mcc": 7217},
        {"industry_type": "Caterers", "mcc": 5811},
        {"industry_type": "Charitable and Social Service Organizations - Fundraising", "mcc": 8398},
        {"industry_type": "Chemicals and Allied Products (Not Elsewhere Classified)", "mcc": 5169},
        {"industry_type": "Child Care Services", "mcc": 8351},
        {"industry_type": "Childrens and Infants Wear Stores", "mcc": 5641},
        {"industry_type": "Chiropodists, Podiatrists", "mcc": 8049},
        {"industry_type": "Chiropractors", "mcc": 8041},
        {"industry_type": "Cigar Stores and Stands", "mcc": 5993},
        {"industry_type": "Civic, Social, Fraternal Associations", "mcc": 8641},
        {"industry_type": "Cleaning and Maintenance", "mcc": 7349},
        {"industry_type": "Clothing Rental", "mcc": 7296},
        {"industry_type": "Colleges, Universities", "mcc": 8220},
        {"industry_type": "Commercial Equipment (Not Elsewhere Classified)", "mcc": 5046},
        {"industry_type": "Commercial Footwear", "mcc": 5139},
        {"industry_type": "Commercial Photography, Art and Graphics", "mcc": 7333},
        {"industry_type": "Commuter Transport, Ferries", "mcc": 4111},
        {"industry_type": "Computer Network Services", "mcc": 4816},
        {"industry_type": "Computer Programming", "mcc": 7372},
        {"industry_type": "Computer Repair", "mcc": 7379},
        {"industry_type": "Computer Software Stores", "mcc": 5734},
        {"industry_type": "Computers, Peripherals, and Software", "mcc": 5045},
        {"industry_type": "Concrete Work Services", "mcc": 1771},
        {"industry_type": "Construction Materials (Not Elsewhere Classified)", "mcc": 5039},
        {"industry_type": "Consulting, Public Relations", "mcc": 7392},
        {"industry_type": "Correspondence Schools", "mcc": 8241},
        {"industry_type": "Cosmetic Stores", "mcc": 5977},
        {"industry_type": "Counseling Services", "mcc": 7277},
        {"industry_type": "Country Clubs", "mcc": 7997},
        {"industry_type": "Courier Services", "mcc": 4215},
        {"industry_type": "Court Costs, Including Alimony and Child Support - Courts of Law", "mcc": 9211},
        {"industry_type": "Credit Reporting Agencies", "mcc": 7321},
        {"industry_type": "Cruise Lines", "mcc": 4411},
        {"industry_type": "Dairy Products Stores", "mcc": 5451},
        {"industry_type": "Dance Hall, Studios, Schools", "mcc": 7911},
        {"industry_type": "Dating/Escort Services", "mcc": 7273},
        {"industry_type": "Dentists, Orthodontists", "mcc": 8021},
        {"industry_type": "Department Stores", "mcc": 5311},
        {"industry_type": "Detective Agencies", "mcc": 7393},
        {"industry_type": "Digital Goods Media Books, Movies, Music", "mcc": 5815},
        {"industry_type": "Digital Goods Applications (Excludes Games)", "mcc": 5817},
        {"industry_type": "Digital Goods Games", "mcc": 5816},
        {"industry_type": "Digital Goods Large Digital Goods Merchant", "mcc": 5818},
        {"industry_type": "Direct Marketing - Catalog Merchant", "mcc": 5964},
        {"industry_type": "Direct Marketing - Combination Catalog and Retail Merchant", "mcc": 5965},
        {"industry_type": "Direct Marketing - Inbound Telemarketing", "mcc": 5967},
        {"industry_type": "Direct Marketing - Insurance Services", "mcc": 5960},
        {"industry_type": "Direct Marketing - Other", "mcc": 5969},
        {"industry_type": "Direct Marketing - Outbound Telemarketing", "mcc": 5966},
        {"industry_type": "Direct Marketing - Subscription", "mcc": 5968},
        {"industry_type": "Direct Marketing - Travel", "mcc": 5962},
        {"industry_type": "Discount Stores", "mcc": 5310},
        {"industry_type": "Doctors", "mcc": 8011},
        {"industry_type": "Door-To-Door Sales", "mcc": 5963},
        {"industry_type": "Drapery, Window Covering, and Upholstery Stores", "mcc": 5714},
        {"industry_type": "Drinking Places", "mcc": 5813},
        {"industry_type": "Drug Stores and Pharmacies", "mcc": 5912},
        {"industry_type": "Drugs, Drug Proprietaries, and Druggist Sundries", "mcc": 5122},
        {"industry_type": "Dry Cleaners", "mcc": 7216},
        {"industry_type": "Durable Goods (Not Elsewhere Classified)", "mcc": 5099},
        {"industry_type": "Duty Free Stores", "mcc": 5309},
        {"industry_type": "Eating Places, Restaurants", "mcc": 5812},
        {"industry_type": "Educational Services", "mcc": 8299},
        {"industry_type": "Electric Razor Stores", "mcc": 5997},
        {"industry_type": "Electric Vehicle Charging", "mcc": 5552},
        {"industry_type": "Electrical Parts and Equipment", "mcc": 5065},
        {"industry_type": "Electrical Services", "mcc": 1731},
        {"industry_type": "Electronics Repair Shops", "mcc": 7622},
        {"industry_type": "Electronics Stores", "mcc": 5732},
        {"industry_type": "Elementary, Secondary Schools", "mcc": 8211},
        {"industry_type": "Emergency Services (GCAS) (Visa use only)", "mcc": 9702},
        {"industry_type": "Employment/Temp Agencies", "mcc": 7361},
        {"industry_type": "Equipment Rental", "mcc": 7394},
        {"industry_type": "Exterminating Services", "mcc": 7342},
        {"industry_type": "Family Clothing Stores", "mcc": 5651},
        {"industry_type": "Fast Food Restaurants", "mcc": 5814},
        {"industry_type": "Financial Institutions", "mcc": 6012},
        {"industry_type": "Fines - Government Administrative Entities", "mcc": 9222},
        {"industry_type": "Fireplace, Fireplace Screens, and Accessories Stores", "mcc": 5718},
        {"industry_type": "Floor Covering Stores", "mcc": 5713},
        {"industry_type": "Florists", "mcc": 5992},
        {"industry_type": "Florists Supplies, Nursery Stock, and Flowers", "mcc": 5193},
        {"industry_type": "Freezer and Locker Meat Provisioners", "mcc": 5422},
        {"industry_type": "Fuel Dealers (Non Automotive)", "mcc": 5983},
        {"industry_type": "Funeral Services, Crematories", "mcc": 7261},
        {"industry_type": "Furniture Repair, Refinishing", "mcc": 7641},
        {"industry_type": "Furniture, Home Furnishings, and Equipment Stores, Except Appliances", "mcc": 5712},
        {"industry_type": "Furriers and Fur Shops", "mcc": 5681},
        {"industry_type": "General Services", "mcc": 1520},
        {"industry_type": "Gift, Card, Novelty, and Souvenir Shops", "mcc": 5947},
        {"industry_type": "Glass, Paint, and Wallpaper Stores", "mcc": 5231},
        {"industry_type": "Glassware, Crystal Stores", "mcc": 5950},
        {"industry_type": "Golf Courses - Public", "mcc": 7992},
        {"industry_type": "Government Licensed On-line Casinos (On-Line Gambling)(US Region only)", "mcc": 7801},
        {"industry_type": "Government Services (Not Elsewhere Classified)", "mcc": 9399},
        {"industry_type": "Government-Licensed Horse/Dog Racing (US Region only)", "mcc": 7802},
        {"industry_type": "Government-Owned Lotteries (Non-US region)", "mcc": 9406},
        {"industry_type": "Government-Owned Lotteries (US Region only)", "mcc": 7800},
        {"industry_type": "Grocery Stores, Supermarkets", "mcc": 5411},
        {"industry_type": "Hardware Stores", "mcc": 5251},
        {"industry_type": "Hardware, Equipment, and Supplies", "mcc": 5072},
        {"industry_type": "Health and Beauty Spas", "mcc": 7298},
        {"industry_type": "Hearing Aids Sales and Supplies", "mcc": 5975},
        {"industry_type": "Heating, Plumbing, A/C", "mcc": 1711},
        {"industry_type": "Hobby, Toy, and Game Shops", "mcc": 5945},
        {"industry_type": "Home Supply Warehouse Stores", "mcc": 5200},
        {"industry_type": "Hospitals", "mcc": 8062},
        {"industry_type": "Hotels, Motels, and Resorts", "mcc": 7011},
        {"industry_type": "Household Appliance Stores", "mcc": 5722},
        {"industry_type": "Industrial Supplies (Not Elsewhere Classified)", "mcc": 5085},
        {"industry_type": "Information Retrieval Services", "mcc": 7375},
        {"industry_type": "Insurance - Default", "mcc": 6399},
        {"industry_type": "Insurance Underwriting, Premiums", "mcc": 6300},
        {"industry_type": "Intra-Company Purchases", "mcc": 9950},
        {"industry_type": "Jewelry Stores, Watches, Clocks, and Silverware Stores", "mcc": 5944},
        {"industry_type": "Landscaping Services", "mcc": 780},
        {"industry_type": "Laundries", "mcc": 7211},
        {"industry_type": "Laundry, Cleaning Services", "mcc": 7210},
        {"industry_type": "Legal Services, Attorneys", "mcc": 8111},
        {"industry_type": "Luggage and Leather Goods Stores", "mcc": 5948},
        {"industry_type": "Lumber, Building Materials Stores", "mcc": 5211},
        {"industry_type": "Manual Cash Disburse", "mcc": 6010},
        {"industry_type": "Marinas, Service and Supplies", "mcc": 4468},
        {"industry_type": "Marketplaces", "mcc": 5262},
        {"industry_type": "Masonry, Stonework, and Plaster", "mcc": 1740},
        {"industry_type": "Massage Parlors", "mcc": 7297},
        {"industry_type": "Medical Services", "mcc": 8099},
        {"industry_type": "Medical and Dental Labs", "mcc": 8071},
        {"industry_type": "Medical, Dental, Ophthalmic, and Hospital Equipment and Supplies", "mcc": 5047},
        {"industry_type": "Membership Organizations", "mcc": 8699},
        {"industry_type": "Mens and Boys Clothing and Accessories Stores", "mcc": 5611},
        {"industry_type": "Mens, Women's Clothing Stores", "mcc": 5691},
        {"industry_type": "Metal Service Centers", "mcc": 5051},
        {"industry_type": "Miscellaneous Apparel and Accessory Shops", "mcc": 5699},
        {"industry_type": "Miscellaneous Auto Dealers", "mcc": 5599},
        {"industry_type": "Miscellaneous Business Services", "mcc": 7399},
        {"industry_type": "Miscellaneous Food Stores - Convenience Stores and Specialty Markets", "mcc": 5499},
        {"industry_type": "Miscellaneous General Merchandise", "mcc": 5399},
        {"industry_type": "Miscellaneous General Services", "mcc": 7299},
        {"industry_type": "Miscellaneous Home Furnishing Specialty Stores", "mcc": 5719},
        {"industry_type": "Miscellaneous Publishing and Printing", "mcc": 2741},
        {"industry_type": "Miscellaneous Recreation Services", "mcc": 7999},
        {"industry_type": "Miscellaneous Repair Shops", "mcc": 7699},
        {"industry_type": "Miscellaneous Specialty Retail", "mcc": 5999},
        {"industry_type": "Mobile Home Dealers", "mcc": 5271},
        {"industry_type": "Motion Picture Theaters", "mcc": 7832},
        {
            "industry_type": "Motor Freight Carriers and Trucking - Local and Long Distance, Moving and Storage Companies, and Local Delivery Services",
            "mcc": 4214,
        },
        {"industry_type": "Motor Homes Dealers", "mcc": 5592},
        {"industry_type": "Motor Vehicle Supplies and New Parts", "mcc": 5013},
        {"industry_type": "Motorcycle Shops and Dealers", "mcc": 5571},
        {"industry_type": "Motorcycle Shops, Dealers", "mcc": 5561},
        {"industry_type": "Music Stores-Musical Instruments, Pianos, and Sheet Music", "mcc": 5733},
        {"industry_type": "News Dealers and Newsstands", "mcc": 5994},
        {"industry_type": "Non-FI, Money Orders", "mcc": 6051},
        {"industry_type": "Non-FI, Stored Value Card Purchase/Load", "mcc": 6540},
        {"industry_type": "Nondurable Goods (Not Elsewhere Classified)", "mcc": 5199},
        {"industry_type": "Nurseries, Lawn and Garden Supply Stores", "mcc": 5261},
        {"industry_type": "Nursing/Personal Care", "mcc": 8050},
        {"industry_type": "Office and Commercial Furniture", "mcc": 5021},
        {"industry_type": "Opticians, Eyeglasses", "mcc": 8043},
        {"industry_type": "Optometrists, Ophthalmologist", "mcc": 8042},
        {"industry_type": "Orthopedic Goods - Prosthetic Devices", "mcc": 5976},
        {"industry_type": "Osteopaths", "mcc": 8031},
        {"industry_type": "Package Stores-Beer, Wine, and Liquor", "mcc": 5921},
        {"industry_type": "Paints, Varnishes, and Supplies", "mcc": 5198},
        {"industry_type": "Parking Lots, Garages", "mcc": 7523},
        {"industry_type": "Passenger Railways", "mcc": 4112},
        {"industry_type": "Pawn Shops", "mcc": 5933},
        {"industry_type": "Pet Shops, Pet Food, and Supplies", "mcc": 5995},
        {"industry_type": "Petroleum and Petroleum Products", "mcc": 5172},
        {"industry_type": "Photo Developing", "mcc": 7395},
        {"industry_type": "Photographic Studios", "mcc": 7221},
        {"industry_type": "Photographic, Photocopy, Microfilm Equipment, and Supplies", "mcc": 5044},
        {"industry_type": "Picture/Video Production", "mcc": 7829},
        {"industry_type": "Piece Goods, Notions, and Other Dry Goods", "mcc": 5131},
        {"industry_type": "Plumbing, Heating Equipment, and Supplies", "mcc": 5074},
        {"industry_type": "Political Organizations", "mcc": 8651},
        {"industry_type": "Postal Services - Government Only", "mcc": 9402},
        {"industry_type": "Precious Stones and Metals, Watches and Jewelry", "mcc": 5094},
        {"industry_type": "Professional Services", "mcc": 8999},
        {
            "industry_type": "Public Warehousing and Storage - Farm Products, Refrigerated Goods, Household Goods, and Storage",
            "mcc": 4225,
        },
        {"industry_type": "Quick Copy, Repro, and Blueprint", "mcc": 7338},
        {"industry_type": "Railroads", "mcc": 4011},
        {"industry_type": "Real Estate Agents and Managers - Rentals", "mcc": 6513},
        {"industry_type": "Record Stores", "mcc": 5735},
        {"industry_type": "Recreational Vehicle Rentals", "mcc": 7519},
        {"industry_type": "Religious Goods Stores", "mcc": 5973},
        {"industry_type": "Religious Organizations", "mcc": 8661},
        {"industry_type": "Roofing/Siding, Sheet Metal", "mcc": 1761},
        {"industry_type": "Secretarial Support Services", "mcc": 7339},
        {"industry_type": "Security Brokers/Dealers", "mcc": 6211},
        {"industry_type": "Service Stations", "mcc": 5541},
        {"industry_type": "Sewing, Needlework, Fabric, and Piece Goods Stores", "mcc": 5949},
        {"industry_type": "Shoe Repair/Hat Cleaning", "mcc": 7251},
        {"industry_type": "Shoe Stores", "mcc": 5661},
        {"industry_type": "Small Appliance Repair", "mcc": 7629},
        {"industry_type": "Snowmobile Dealers", "mcc": 5598},
        {"industry_type": "Special Trade Services", "mcc": 1799},
        {"industry_type": "Specialty Cleaning", "mcc": 2842},
        {"industry_type": "Sporting Goods Stores", "mcc": 5941},
        {"industry_type": "Sporting/Recreation Camps", "mcc": 7032},
        {"industry_type": "Sports Clubs/Fields", "mcc": 7941},
        {"industry_type": "Sports and Riding Apparel Stores", "mcc": 5655},
        {"industry_type": "Stamp and Coin Stores", "mcc": 5972},
        {"industry_type": "Stationary, Office Supplies, Printing and Writing Paper", "mcc": 5111},
        {"industry_type": "Stationery Stores, Office, and School Supply Stores", "mcc": 5943},
        {"industry_type": "Swimming Pools Sales", "mcc": 5996},
        {"industry_type": "TUI Travel - Germany", "mcc": 4723},
        {"industry_type": "Tailors, Alterations", "mcc": 5697},
        {"industry_type": "Tax Payments - Government Agencies", "mcc": 9311},
        {"industry_type": "Tax Preparation Services", "mcc": 7276},
        {"industry_type": "Taxicabs/Limousines", "mcc": 4121},
        {"industry_type": "Telecommunication Equipment and Telephone Sales", "mcc": 4812},
        {"industry_type": "Telecommunication Services", "mcc": 4814},
        {"industry_type": "Telegraph Services", "mcc": 4821},
        {"industry_type": "Tent and Awning Shops", "mcc": 5998},
        {"industry_type": "Testing Laboratories", "mcc": 8734},
        {"industry_type": "Theatrical Ticket Agencies", "mcc": 7922},
        {"industry_type": "Timeshares", "mcc": 7012},
        {"industry_type": "Tire Retreading and Repair", "mcc": 7534},
        {"industry_type": "Tolls/Bridge Fees", "mcc": 4784},
        {"industry_type": "Tourist Attractions and Exhibits", "mcc": 7991},
        {"industry_type": "Towing Services", "mcc": 7549},
        {"industry_type": "Trailer Parks, Campgrounds", "mcc": 7033},
        {"industry_type": "Transportation Services (Not Elsewhere Classified)", "mcc": 4789},
        {"industry_type": "Travel Agencies, Tour Operators", "mcc": 4722},
        {"industry_type": "Truck/Utility Trailer Rentals", "mcc": 7513},
        {"industry_type": "Typesetting, Plate Making, and Related Services", "mcc": 2791},
        {"industry_type": "Typewriter Stores", "mcc": 5978},
        {"industry_type": "U.S. Federal Government Agencies or Departments", "mcc": 9405},
        {"industry_type": "Uniforms, Commercial Clothing", "mcc": 5137},
        {"industry_type": "Used Merchandise and Secondhand Stores", "mcc": 5931},
        {"industry_type": "Utilities", "mcc": 4900},
        {"industry_type": "Variety Stores", "mcc": 5331},
        {"industry_type": "Veterinary Services", "mcc": 742},
        {"industry_type": "Video Amusement Game Supplies", "mcc": 7993},
        {"industry_type": "Video Game Arcades", "mcc": 7994},
        {"industry_type": "Video Tape Rental Stores", "mcc": 7841},
        {"industry_type": "Vocational/Trade Schools", "mcc": 8249},
        {"industry_type": "Watch/Jewelry Repair", "mcc": 7631},
        {"industry_type": "Welding Repair", "mcc": 7692},
        {"industry_type": "Wholesale Clubs", "mcc": 5300},
        {"industry_type": "Wig and Toupee Stores", "mcc": 5698},
        {"industry_type": "Wires, Money Orders", "mcc": 4829},
        {"industry_type": "women's Accessory and Specialty Shops", "mcc": 5631},
        {"industry_type": "women's Ready-To-Wear Stores", "mcc": 5621},
        {"industry_type": "Wrecking and Salvage Yards", "mcc": 5935},
    ]
    ```
  </Tab>
</Tabs>

> **Payload Example:**

```json Payload theme={null}
{
  "mcc": "6012"
}
```


# Changelog
Source: https://developer.paywint.com/resources/changelog

Track all improvements, new features, fixes, and updates made to the Paywint API and Documentation.

The Paywint Changelog records all updates across the API, documentation, dashboards, and platform features.

<Update label="12-01-2025" description="v0.1.0">
  Major documentation update, including:

  * Restructured API reference navigation
  * Expanded coverage for payments, bank accounts, wallet, and compliance
  * Added Payee management, Check mailing, and Paywint Bank Account sections
  * Introduced the URL Standards guideline set
  * Improved consistency, formatting, and page organization
</Update>


# FAQ
Source: https://developer.paywint.com/resources/faq

Frequently Asked Questions about the Paywint API.

## General Questions

### What is the Paywint API?

The Paywint API allows you to integrate financial services such as payment processing, wallet management, user creation, and more into your application. With our easy-to-use endpoints, you can manage users, make payments, and integrate features like ACH transactions, wallet funding, and card management.

### How do I get started with the Paywint API?

To get started, you’ll need to sign up for an account on Paywint. Once you're signed up, you can generate your API key in the dashboard and start using the API. Visit our [Get Started](https://paywint.com/get-started) guide for more details.

## Authentication

### How do I authenticate my API requests?

Paywint uses API key-based authentication. You can obtain an API key from the dashboard and include it in the `Authorization` header of your API requests. For example:

```bash theme={null}
curl -X GET https://api.paywint.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### How do I secure my API key?

Never expose your API key in your frontend code or public repositories. Always store it in a secure backend environment, such as environment variables, and use it server-side to sign API requests.

## Webhooks

### What are webhooks and how do I set them up?

Webhooks allow you to receive real-time updates about events happening in your Paywint account, such as payment success, wallet funding, and KYC verification. You need to configure a URL in your dashboard to receive webhook notifications. You can find detailed instructions on setting up webhooks in our [Webhooks Setup Guide](/webhooks/setup).

## Billing & Payments

### How do I manage payments in the Paywint API?

The Paywint API provides several endpoints for managing payments, including creating payments, checking payment status, and listing payments. Visit our [Payments API Reference](/api-reference/payments/overview) for more details.

## Support

### How can I contact Paywint support?

If you need assistance, you can reach out to our support team via email at [support@paywint.com](mailto:support@paywint.com). We also offer live chat on our website and support through our [community forums](https://community.paywint.com).

## Still have questions?

If you didn’t find an answer here, feel free to reach out to our support team at [support@paywint.com](mailto:support@paywint.com). We’re happy to assist you!


# Glossary
Source: https://developer.paywint.com/resources/glossary

A list of terms and definitions related to the Paywint API and payment processing.

## Signature Verification

The process of ensuring that a request or webhook payload was sent by Paywint and hasn’t been tampered with. Paywint includes a signature in each request and webhook, which you can verify using a shared secret key.

## Sandbox Environment

A testing environment where developers can safely test API calls and integrations without affecting real-world data. Paywint provides a **Sandbox** environment for developers to test their integration before going live.

## Production Environment

The live environment where real transactions are processed. Once you’ve successfully tested in the Sandbox, you can switch to the **Production** environment to start handling actual user data and payments.

## Response Codes

Numerical codes returned by the server in response to an API request, indicating the result of the request. Common codes include:

* `200 OK`: Request was successful.
* `400 Bad Request`: The request was malformed or invalid.
* `422 Unprocessable Entity`:  Input data does not meet defined constraints.

***

## Still confused?

If you come across terms that aren't listed here or need more clarification, feel free to reach out to our support team at [support@paywint.com](mailto:support@paywint.com). We're here to help!


# Event Types
Source: https://developer.paywint.com/webhooks/event-types

Complete list of webhook event types sent by Paywint.

Below is the list of all webhook event types Paywint can send to your webhook endpoint.\
Each corresponds to a significant system action or user state update.

***

## KYC Events

| Event           | Description                 |
| --------------- | --------------------------- |
| `kyc.applied`   | User submitted KYC details. |
| `kyc.approved`  | KYC verification approved.  |
| `kyc.rejected`  | KYC verification rejected.  |
| `kyc.failed`    | KYC verification failed.    |
| `kyc.completed` | KYC process completed.      |
| `kyc.deleted`   | KYC record deleted.         |

## KYB Events

| Event          | Description                |
| -------------- | -------------------------- |
| `kyb.approved` | KYB verification approved. |
| `kyb.rejected` | KYB verification rejected. |
| `kyb.deleted`  | KYB record deleted.        |

## Wallet Funding Events

| Event                       | Description                       |
| --------------------------- | --------------------------------- |
| `wallet.funding.initiated`  | Wallet funding request initiated. |
| `wallet.funding.processing` | Wallet funding in progress.       |
| `wallet.funding.success`    | Wallet funding successful.        |
| `wallet.funding.failed`     | Wallet funding failed.            |
| `wallet.funding.rejected`   | Wallet funding rejected.          |

## Wallet Withdrawal Events

| Event                          | Description             |
| ------------------------------ | ----------------------- |
| `wallet.withdrawal.initiated`  | Withdrawal initiated.   |
| `wallet.withdrawal.processing` | Withdrawal in progress. |
| `wallet.withdrawal.settling`   | Withdrawal settling.    |
| `wallet.withdrawal.success`    | Withdrawal successful.  |
| `wallet.withdrawal.failed`     | Withdrawal failed.      |
| `wallet.withdrawal.rejected`   | Withdrawal rejected.    |

## Card Events

| Event                  | Description                     |
| ---------------------- | ------------------------------- |
| `card.added`           | A new card was added.           |
| `card.images_uploaded` | Card images have been uploaded. |

## Payment Events

| Event                                                          | Description                            |
| -------------------------------------------------------------- | -------------------------------------- |
| [payment.opened](/webhooks/events/payment/opened)              | Payment link opened by user.           |
| [payment.initiated](/webhooks/events/payment/initiated)        | Payment initiated.                     |
| [payment.processing](/webhooks/events/payment/processing)      | Payment requires processing or review. |
| [payment.settling](/webhooks/events/payment/settling)          | Payment settling.                      |
| [payment.success](/webhooks/events/payment/success)            | Payment successfully completed.        |
| [payment.failed](/webhooks/events/payment/failed)              | Payment attempt failed.                |
| [payment.rejected](/webhooks/events/payment/rejected)          | Payment rejected.                      |
| [payment.refunded](/webhooks/events/payment/refunded)          | Payment refunded.                      |
| [payment.fee\_refunded](/webhooks/events/payment/fee-refunded) | Payment fee refunded.                  |

## Next Steps

* Learn to **verify webhook signatures** to ensure authenticity.
* Review **retry behavior** for undelivered events [Retry Behavior](/webhooks/retry-behavior).
* Check **event-specific payloads** in the [Event Reference](/webhooks/webhook-response).


# Events
Source: https://developer.paywint.com/webhooks/events

Understand how Paywint webhook events work and what they represent.

Events represent actions or state changes that occur within Paywint — such as a payment completing, a wallet being funded, or a user’s KYC being approved.

When these actions happen, Paywint sends an **event notification** to your registered webhook endpoint.

***

## What Are Events?

Every event is a JSON payload sent via HTTP `POST` to your webhook URL.\
It contains metadata describing **what happened**, **which resource was affected**, and **when it occurred**.

**Example Payload**

```json theme={null}
{
  "event": "payment.success",
  "id": "evt_83a2bfc1",
  "data": {
    "payment_id": "pay_93fdc2",
    "amount": "100.00",
    "currency": "USD",
    "status": "success"
  },
  "eventGeneratedTime": 1718006400
}
```

| Field                | Description                                        |
| -------------------- | -------------------------------------------------- |
| `event`              | Event name (e.g., `payment.success`).              |
| `id`                 | Unique identifier for this specific webhook event. |
| `data`               | The event-specific data payload.                   |
| `eventGeneratedTime` | UNIX timestamp when the event occurred.            |

***

## Event Delivery Flow

1. An event occurs within Paywint (e.g., `payment.success`).
2. Paywint sends a webhook `POST` request to your configured endpoint.
3. Your server validates the signature and processes the event.
4. Paywint expects a `2xx` response code to confirm successful receipt.

If your endpoint does not respond with `2xx`, Paywint retries delivery according to its [Retry Behavior](/webhooks/retry-behavior) policy.

***

## Event Naming Convention

All event names use **dot notation**, formatted as:

```
<object>.<action>
```

Examples:

* `kyc.approved` — A user’s KYC verification succeeded.
* `wallet.funding.success` — A wallet was successfully funded.
* `payment.failed` — A payment attempt failed.

***

## Next Steps

* View the complete list of event names — see [Event Types](/webhooks/event-types).
* Learn to validate event authenticity — see [Signature Verification](/webhooks/signature-verification).
* Review event retry logic — see [Retry Behavior](/webhooks/retry-behavior).

<Card title="View Event Types" icon="list" href="/webhooks/event-types">
  Browse all available webhook event types and their meanings.
</Card>


# payment.failed
Source: https://developer.paywint.com/webhooks/events/payment/failed

Sent when a payment fails.

The `payment.failed` event is sent when a payment attempt **fails** and the transaction reaches a **final, non-recoverable state**.

After this event is emitted, the payment will not continue processing.

***

## Example Payload

```json theme={null}
{
  "event": "payment.failed",
  "id": "77b568f8-cc38-4b5c-91aa-ac3c77020963",
  "data": {
    "payment_id": "ac4bedda-f370-4ac4-a61e-e1761a5a51b9",
    "status": "failed",
    "amount": 599,
    "failed_reason": "Transaction could not be processed. Try again later."
  },
  "eventGeneratedTime": 1756452659.868249
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Final payment status. Always <code>failed</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

<ResponseField name="failed_reason" type="string">
  Human-readable explanation describing why the payment failed.
</ResponseField>

## Handling the Event

Use this event to:

* Update the payment record to a failed state
* Synchronize failure status across systems
* Record failure details for auditing or analysis
* Determine next steps based on your application logic

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)


# payment.fee_refunded
Source: https://developer.paywint.com/webhooks/events/payment/fee-refunded

Sent when a payment fee has been successfully refunded.

The `payment.fee_refunded` event is sent when a **fee associated with a payment** has been **successfully refunded**.

This event applies only to the refunded fee amount and does not affect the original payment status.

***

## Example Payload

```json theme={null}
{
  "event": "payment.fee_refunded",
  "id": "a550ba77-09ac-4bc7-9d5b-505a5135f3b6",
  "data": {
    "payment_id": "a550ba77-09ac-4bc7-9d5b-505a5135f3b6",
    "status": "success",
    "amount": 10.0,
    "refund_transaction_id": "4f2f7785-d5d0-4202-a95f-af4968535775"
  },
  "eventGeneratedTime": 1756729948.128641
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier of the original payment.
</ResponseField>

<ResponseField name="status" type="string">
  Refund status. Always <code>success</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Refunded fee amount represented as a decimal in the transaction currency.
</ResponseField>

<ResponseField name="refund_transaction_id" type="string">
  Unique identifier for the fee refund transaction.
</ResponseField>

## Handling the Event

Use this event to:

* Record refunded fees linked to a payment
* Update accounting or reconciliation records
* Synchronize refund activity across systems
* Track fee-level adjustments independently of payment status

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.initiated
Source: https://developer.paywint.com/webhooks/events/payment/initiated

Sent when a payment attempt is initiated.

The `payment.initiated` event is sent when a payment has **transitioned from an open state into an active attempt**.

This event indicates that the payment has begun its execution flow but has not yet entered processing or any other state.

***

## Example Payload

```json theme={null}
{
  "event": "payment.initiated",
  "id": "1c5e92e7-4b2b-4a0a-8d7a-8d31f7b52e9a",
  "data": {
    "payment_id": "f4b3d09e-4b27-4c44-9d41-6f7e8a4a2c11",
    "status": "initiated",
    "amount": 599
  },
  "eventGeneratedTime": 1756721043.214908
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status. Always <code>initiated</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

## Handling the Event

Use this event to:

* Record the start of a payment attempt
* Transition the payment into an active state
* Prevent duplicate initiation of the same payment
* Monitor payment flow progression

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.opened
Source: https://developer.paywint.com/webhooks/events/payment/opened

Sent when a payment is created and awaiting further action.

The `payment.opened` event is sent when a payment has been **created** and is in an **open state**, but has not yet begun processing.

This event indicates that the payment exists and is awaiting the next step in its lifecycle.

***

## Example Payload

```json theme={null}
{
  "event": "payment.opened",
  "id": "60a71435-d079-4126-81a2-1977bb70a306",
  "data": {
    "payment_id": "a5299046-1f62-4f78-8239-6e724d99c38b",
    "status": "opened",
    "amount": 599
  },
  "eventGeneratedTime": 1756717250.451172
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status. Always <code>opened</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

## Handling the Event

Use this event to:

* Record the creation of a new payment
* Track payments that have not yet progressed
* Maintain visibility into pending or idle payment states
* Trigger internal logic that depends on payment availability

***

## Related Events

* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.processing
Source: https://developer.paywint.com/webhooks/events/payment/processing

Sent when a payment is being processed.

The `payment.processing` event is sent when a payment is **actively being processed** and has **not yet completed**.

This event indicates that the payment has moved beyond initiation and is awaiting completion or failure.

***

## Example Payload

```json theme={null}
{
  "event": "payment.processing",
  "id": "99036bd3-a8b2-403c-867c-3d03dafbe4b7",
  "data": {
    "payment_id": "b91a0f36-b10b-4a31-ae12-e8b4c5ee71f4",
    "status": "processing",
    "amount": 599
  },
  "eventGeneratedTime": 1756451608.069325
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status. Always <code>processing</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

## Handling the Event

Use this event to:

* Update the payment record to a processing state
* Prevent duplicate or conflicting payment actions
* Reflect an in-progress state within your system

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.refund
Source: https://developer.paywint.com/webhooks/events/payment/refunded

Sent when a payment amount is successfully refunded.

The `payment.refund` event is sent when a payment amount has been **successfully refunded** and the refund process has completed.

This event represents a completed refund transaction associated with an existing payment.

***

## Example Payload

```json theme={null}
{
  "event": "payment.refund",
  "id": "a70f3889-7a4f-4ec0-a3c0-652fdfa323db",
  "data": {
    "payment_id": "a70f3889-7a4f-4ec0-a3c0-652fdfa323db",
    "status": "completed",
    "amount": 1000.0,
    "refund_transaction_id": "539d185f-8586-4714-bde5-351a6c38a191"
  },
  "eventGeneratedTime": 1756731284.557921
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier of the original payment.
</ResponseField>

<ResponseField name="status" type="string">
  Refund status. Always <code>completed</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Refunded amount represented as a decimal in the transaction currency.
</ResponseField>

<ResponseField name="refund_transaction_id" type="string">
  Unique identifier for the refund transaction.
</ResponseField>

## Handling the Event

Use this event to:

* Record completed refund transactions
* Update balances or accounting records
* Synchronize refund state across systems
* Track refunded amounts independently of payment execution

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.rejected
Source: https://developer.paywint.com/webhooks/events/payment/rejected

Sent when a payment is rejected before processing begins.

The `payment.rejected` event is sent when a payment attempt is **explicitly rejected** and does not proceed to processing.

This event indicates that the payment was blocked due to validation rules, risk checks, compliance requirements, or other pre-processing conditions.

***

## Example Payload

```json theme={null}
{
  "event": "payment.rejected",
  "id": "3b8b71e4-8f4e-4e6c-bbb2-1b7b4c6d9e21",
  "data": {
    "payment_id": "9f4e1a2b-3c8d-4f92-9c27-1e5b8c4f7a63",
    "status": "rejected",
    "amount": 599
  },
  "eventGeneratedTime": 1756723891.902114
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Final payment status. Always <code>rejected</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

## Handling the Event

Use this event to:

* Update the payment record to a rejected state
* Prevent the payment from progressing further
* Record rejection details for auditing or review
* Apply application-specific logic based on rejection outcomes

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.success](/webhooks/events/payment/success)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.settling
Source: https://developer.paywint.com/webhooks/events/payment/settling

Sent when a payment is in the process of being settled.

The `payment.settling` event is sent when a payment has completed processing and the **settlement process has begun**.

This state indicates that the payment amount is being **settled to the destination card** and has not yet reached final settlement.

***

## Example Payload

```json theme={null}
{
  "event": "payment.settling",
  "id": "3b8b71e4-8f4e-4e6c-bbb2-1b7b4c6d9e21",
  "data": {
    "payment_id": "9f4e1a2b-3c8d-4f92-9c27-1e5b8c4f7a63",
    "status": "settling",
    "amount": 599
  },
  "eventGeneratedTime": 1756723891.902114
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Current payment status. Always <code>settling</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount represented as a decimal in the transaction currency.
</ResponseField>

## Handling the Event

Use this event to:

* Track payments that are undergoing settlement
* Reflect a settling or pending balance state in your system
* Prevent duplicate settlement actions
* Monitor settlement progress before final completion

***

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.success](/webhooks/events/payment/success)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# payment.success
Source: https://developer.paywint.com/webhooks/events/payment/success

Sent when a payment is successfully completed.

The `payment.success` event is sent when a payment has been **successfully completed** and funds have been confirmed.

Use this webhook to mark transactions as completed, grant access to services, or trigger fulfillment workflows in your system.

***

## Example Payload

```json theme={null}
{
  "event": "payment.success",
  "id": "99036bd3-a8b2-403c-867c-3d03dafbe4b7",
  "data": {
    "payment_id": "b91a0f36-b10b-4a31-ae12-e8b4c5ee71f4",
    "status": "success",
    "amount": 599
  },
  "eventGeneratedTime": 1756451608.069325
}
```

***

## Data Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Final status of the payment. Always <code>success</code> for this event.
</ResponseField>

<ResponseField name="amount" type="float">
  Payment amount expressed in the major currency unit (for example, USD).
</ResponseField>

## Handling the Event

Use this event to:

* Mark the payment as completed in your system
* Unlock purchased content or services
* Trigger fulfillment or settlement workflows
* Notify users of successful payment completion

## Related Events

* [payment.opened](/webhooks/events/payment/opened)
* [payment.initiated](/webhooks/events/payment/initiated)
* [payment.processing](/webhooks/events/payment/processing)
* [payment.settling](/webhooks/events/payment/settling)
* [payment.rejected](/webhooks/events/payment/rejected)
* [payment.fee-refunded](/webhooks/events/payment/fee-refunded)
* [payment.refunded](/webhooks/events/payment/refunded)
* [payment.failed](/webhooks/events/payment/failed)


# Overview
Source: https://developer.paywint.com/webhooks/overview

Learn how Paywint uses webhooks to deliver real-time event notifications.

Paywint webhooks allow your application to receive **real-time notifications** whenever an event occurs — such as a payment success, wallet funding, or KYC approval.

Webhooks are essential for keeping your system synchronized without the need for polling the API.\
They let you automatically respond to user and transaction updates as they happen.

***

## How Webhooks Work

1. You register a single HTTPS endpoint (e.g., `https://yourapp.com/webhook`).
2. Paywint sends a `POST` request to that URL whenever an event occurs.
3. Your endpoint verifies the request’s signature for authenticity.
4. Your system processes the event and returns a `200 OK` response.

<CardGroup>
  <Card title="Webhook Setup" icon="cog" href="/webhooks/setup">
    Learn how to configure webhook URLs for Sandbox and Production.
  </Card>

  <Card title="Webhook Events" icon="shield" href="/webhooks/events">
    Ensure webhook events are configured.
  </Card>
</CardGroup>

***

## Use Cases

* Automatically update payment or wallet statuses in your app.
* Send notifications to users on successful transactions.
* Track verification events for users and businesses.
* Reconcile real-time balances and payouts.

***

## Next Steps

* Configure endpoints in **Sandbox** and **Production** — see [Webhook Setup](/webhooks/setup).
* Learn about delivery retries — see [Retry Behavior](/webhooks/retry-behavior).
* Explore webhook events and available event types — see [Events](/webhooks/events).

<Card title="Explore Events" icon="radio" href="/webhooks/events">
  Understand webhook events and how they drive Paywint's real-time updates.
</Card>


# Retry Behavior
Source: https://developer.paywint.com/webhooks/retry-behavior

Understand Paywint webhook delivery and retry logic.

Paywint guarantees **at-least-once** delivery for all webhook events.\
If your endpoint does not return a `2xx` HTTP response, the system automatically retries.

***

## Retry Policy

| Attempt       | Delay after previous try | Condition             |
| ------------- | ------------------------ | --------------------- |
| 1st (initial) | —                        | Original delivery     |
| 2nd           | \~1 minute               | No `2xx` response     |
| 3rd           | \~5 minutes              | Second attempt failed |

After the final failed attempt, an email is sent to the registered **admin address** with details of the undelivered event.

***

## Best Practices

* Return `200 OK` **within 5 seconds**; offload heavy work to background jobs.
* Store and de-duplicate by `event id` to ensure idempotency.
* Implement exponential backoff if you **replay** events from your side.
* Monitor endpoint health (latency and error rates).


# Webhook Setup
Source: https://developer.paywint.com/webhooks/setup

Configure webhook URLs in Sandbox and Production environments.

Before receiving webhook notifications, you must register your endpoint URL within your Paywint dashboard.

***

## Sandbox Environment

Use the **Sandbox environment** to test webhook delivery before going live.

1. **Create a Sandbox Account**\
   Sign up at **sandbox.merchant.paywint.com**.

2. **Generate an API Key**\
   Go to **Settings → API Credentials** to generate your Sandbox API key.\
   [Open Sandbox Settings → API Key](https://sandbox.merchant.paywint.com/app/settings/api-credentials)

3. **Configure Webhook URL**\
   Navigate to **Settings → Redirect/Webhook** and add your webhook endpoint.\
   Example:
   ```text theme={null}
   https://example.com/webhook
   ```

4. **Test Webhook Delivery**
   Use test events to confirm your endpoint correctly receives payloads.

***

## Production Environment

Once you’ve tested successfully in Sandbox, repeat these steps in the **Production environment**.

1. **Create a Production Account**
   Visit **merchant.paywint.com**.

2. **Enable Production Access**
   Contact **[support@paywint.com](mailto:support@paywint.com)** to activate production credentials.

3. **Generate Production API Key**
   From **Settings → API Credentials**, copy your live key.
   [Open Production Settings → API Key](https://merchant.paywint.com/app/settings/api-credentials)

4. **Add Webhook URL**
   Configure your production webhook endpoint in **Settings → Redirect/Webhook**.
   Example:

   ```text theme={null}
   https://yourapp.com/webhook
   ```

5. **Support Contacts**

   * **Email:** [support@paywint.com](mailto:support@paywint.com)
   * **Phone:** +1 (408) 461-5543

***

## Best Practices

* Use **HTTPS** for all webhook endpoints.
* Return **`200 OK` quickly**; process heavy work asynchronously.
* Log event **IDs** and timestamps for idempotency and auditing.
* Secure storage of your **webhook signing secret** is mandatory.


# Signature Verification
Source: https://developer.paywint.com/webhooks/signature-verification

Verify that webhook payloads are securely delivered by Paywint.

## Security Recommendations

* Require **HTTPS** and validate certificates.
* Enforce a **timestamp tolerance window** (e.g., 5 minutes).
* **Log and monitor** verification failures.
* Respond with **`200 OK` only after** successful verification.


# Webhook Responses
Source: https://developer.paywint.com/webhooks/webhook-response

Learn how to receive and handle Paywint webhook events.

## Webhook Structure

Every webhook payload shares the same top-level structure:

<ResponseField name="event" type="string">
  The event name indicating what happened
</ResponseField>

<ResponseField name="id" type="string">
  Unique event identifier (UUID v4 format)
</ResponseField>

<ResponseField name="data" type="object">
  Event-specific fields containing relevant information
</ResponseField>

<ResponseField name="eventGeneratedTime" type="float">
  UNIX timestamp in seconds when the event was generated
</ResponseField>

# Payment Status Webhooks

Paywint sends webhook events to notify your application about payment status changes. This allows you to keep your system synchronized with payment updates in real-time.

## Payment Events

### Payment Opened

Sent when a payment link has been opened by as user to initiate payment.

```json theme={null}
{
  "event": "payment.opened",
  "id": "60a71435-d079-4126-81a2-1977bb70a306",
  "data": {
    "payment_id": "a5299046-1f62-4f78-8239-6e724d99c38b",
    "status": "opened",
    "amount": 599
  },
  "eventGeneratedTime": 1756717250.451172
}
```

### Payment Processing

Sent when a payment requires additional processing time or manual review.

```json theme={null}
{
  "event": "payment.processing",
  "id": "b0ec03ca-822d-44fd-9407-de48a92a09a6",
  "data": {
    "payment_id": "5cd7a3c1-4b45-4148-b383-299553699745",
    "status": "processing",
    "amount": 599
  },
  "eventGeneratedTime": 1756452761.422979
}
```

### Payment Succeeded

Sent when a payment is successfully processed and completed.

```json theme={null}
{
  "event": "payment.success",
  "id": "99036bd3-a8b2-403c-867c-3d03dafbe4b7",
  "data": {
    "payment_id": "b91a0f36-b10b-4a31-ae12-e8b4c5ee71f4",
    "status": "success",
    "amount": 599
  },
  "eventGeneratedTime": 1756451608.069325
}
```

### Payment Failed

Sent when a payment attempt fails due to various reasons such as insufficient funds or gateway rejections.

```json theme={null}
{
  "event": "payment.failed",
  "id": "77b568f8-cc38-4b5c-91aa-ac3c77020963",
  "data": {
    "payment_id": "ac4bedda-f370-4ac4-a61e-e1761a5a51b9",
    "status": "failed",
    "amount": 599,
    "failed_reason": "Transaction could not be processed. Try again later."
  },
  "eventGeneratedTime": 1756452659.868249
}
```

### Payment Retried

Sent when a payment attempt fails and the user initiates a retry. Note that retrying creates a new payment transaction, which is why a `retry_payment_id` is provided for reference.

```json theme={null}
{
  "event": "payment.retried",
  "id": "21b88258-9ff7-4a45-b2e3-85fe33709055",
  "data": {
    "payment_id": "998613a7-df7b-4f56-9297-b49a31e183d9",
    "status": "retried",
    "retry_payment_id": "ac4bedda-f370-4ac4-a61e-e1761a5a51b9",
    "amount": 33
  },
  "eventGeneratedTime": 1756452627.595624
}
```

### Payment Rejected

Sent when a payment is rejected due to policy violations.

```json theme={null}
{
  "event": "payment.rejected",
  "id": "12345678-9abc-def0-1234-56789abcdef0",
  "data": {
    "payment_id": "472a27f5-5e1a-42b6-b61c-8a8c6d35a877",
    "status": "rejected",
    "amount": 599,
  },
  "eventGeneratedTime": 1756375999.456789
}
```

### Payment Expired

Sent when a payment link can no longer be used because it has passed its expiry. No further payment attempts can be initiated against this link; users must request a new link (which will create a new payment).

```json theme={null}
{
  "event": "payment.expired",
  "id": "60a71435-d079-4126-81a2-1977bb70a306",
  "data": {
    "payment_id": "a5299046-1f62-4f78-8239-6e724d99c38b",
    "status": "expired",
    "amount": 599
  },
  "eventGeneratedTime": 1756717250.451172
}
```

***

## Data Fields Reference

### Common Fields

<ResponseField name="payment_id" type="string">
  Unique identifier for the payment transaction
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the payment
</ResponseField>

<ResponseField name="amount" type="integer">
  Payment amount in the smallest currency unit (cents for USD)
</ResponseField>

### Event-Specific Fields

<ResponseField name="failed_reason" type="string">
  Detailed explanation when a payment fails (payment.failed events only)
</ResponseField>

<ResponseField name="retry_payment_id" type="string">
  Unique identifier for retry transactions (payment.retried events only)
</ResponseField>

## Handling Webhooks

### Best Practices

1. **Acknowledge quickly**: Return a 200 HTTP status code as soon as possible
2. **Process asynchronously**: Handle the actual business logic in background jobs
3. **Implement idempotency**: Use the event `id` to prevent duplicate processing

<Warning>
  Webhook endpoints must respond with a 2xx HTTP status code within 30 seconds. Failed deliveries will be retried with exponential backoff.
</Warning>