# Create Payee Address
Source: https://docs.paywint.com/api-reference/payees/address/create-address

POST /api/user-api/address/payee/create
Create an address record for a payee.

An address represents a location associated with a payee and may be used across multiple Paywint services.

This endpoint allows you to:
- Store billing or delivery address details
- Support paywint card issuance workflows
- Associate a location with future payment products
- Maintain structured address records
- Designate a primary (default) address

A payee may have multiple addresses, but only one can be marked as default.



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

DELETE /api/user-api/address/payee/delete
Delete an address associated with a payee.

This endpoint allows you to:
- Remove outdated or invalid location records
- Maintain clean beneficiary records
- Prevent incorrect billing or fulfillment usage
- Promote another address as default if required

If the deleted address was marked as default, another saved address may automatically be promoted.



# Get Payee Address
Source: https://docs.paywint.com/api-reference/payees/address/get-address

POST /api/user-api/address/payee/get
Retrieve a specific address associated with a payee.

This endpoint allows you to:
- Confirm billing or location information
- Validate address details before issuing a paywint card
- Display stored address data in your system
- Verify default address status



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

GET /api/user-api/address/payee/list/{payee_id}
Retrieve all addresses saved for a payee.

This endpoint allows you to:
- Display multiple billing or location records
- Support selection of address during product issuance
- Review default and alternate addresses
- Maintain complete and organized payee records
- Prepare for future Paywint services tied to address data



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

Manage address records associated with a payee.

The **Payee Address API** allows you to create and manage address records associated with an existing payee.

A payee address represents the physical mailing or address linked to a recipient identity.

Payee records must exist before an address can be attached.

***

## What This API Provides

The Payee Address API enables your integration to:

* Add an address to an existing payee
* Retrieve a stored payee address
* Update address details
* Delete an address when it is no longer valid

All address fields should follow standard US postal formatting when applicable.

***

## Available APIs

<CardGroup>
  <Card title="Create Address" icon="plus-circle" href="/api-reference/payees/address/create-address">
    Attach a new address to an existing payee.
  </Card>

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

  <Card title="Get Address" icon="map-pin" href="/api-reference/payees/address/get-address">
    Retrieve a specific address by ID.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Update Address" icon="pencil" href="/api-reference/payees/address/update-address">
    Modify an existing address record.
  </Card>

  <Card title="Set Default Address" icon="check-circle" href="/api-reference/payees/address/set-default-address">
    Mark an address as the default address for the payee.
  </Card>

  <Card title="Delete Address" icon="trash" href="/api-reference/payees/address/delete-address">
    Remove an address from a payee.
  </Card>
</CardGroup>

***

## Typical Integration Flow

<Steps>
  <Step title="1. Ensure payee exists">
    Create the payee using the Payee API before attaching an address.
  </Step>

  <Step title="2. Create the address">
    Call <code>[Create Payee Address](/api-reference/payees/address/create-address)</code> with properly formatted address fields.
  </Step>

  <Step title="3. Maintain accuracy">
    Update address details if the recipient relocates or information changes.
  </Step>

  <Step title="4. Remove outdated addresses">
    Delete addresses that are no longer valid.
  </Step>
</Steps>

***

## Best Practices

* Store state values using two-letter abbreviations (example: `CA`, `NY`, `TX`).
* Use ISO country codes (example: `US`).
* Validate ZIP codes before submission.
* Avoid storing multiple conflicting addresses for the same payee unless required by your business logic.


# Set Default Payee Address
Source: https://docs.paywint.com/api-reference/payees/address/set-default-address

PUT /api/user-api/address/payee/set-default
Designate an address as the default for a payee.

The default address may be used for:
- Paywint card billing purposes
- Card issuance
- Primary delivery handling
- Default compliance reference

This endpoint allows you to:
- Change the primary address
- Ensure consistent operational processing
- Override previous default settings

Only one address per payee may be designated as default at any time.



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

PATCH /api/user-api/address/payee/update
Update an existing address associated with a payee.

This endpoint allows you to:
- Modify billing or location details
- Correct street, city, state, or ZIP code
- Keep records aligned with compliance requirements
- Update default designation if needed
- Maintain accurate location data for Paywint services



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

POST /api/user-api/payee/create
Creates a new payee under your account.

This endpoint allows you to:
- Register a payout recipient before initiating transfers
- Store payee information for repeat payments
- Save recipients for future payouts
- Organize and manage payout beneficiaries



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

DELETE /api/user-api/payee/delete/{payee_id}
Delete a payee from your account.

This endpoint allows you to:
- Remove inactive or outdated beneficiaries
- Maintain clean payout records
- Prevent additional transfers to that payee
- Reduce operational and compliance risk

Once deleted, the payee cannot be used for future payouts unless recreated.



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

GET /api/user-api/payee/get/{payee_id}
Retrieve a specific payee saved under your account.

This endpoint allows you to:
- Confirm payee details before sending funds
- Validate recipient information for compliance
- Display beneficiary information in your system



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

GET /api/user-api/payee/list
Retrieve all payees saved under your account.

This endpoint allows you to:
- Display all payout recipients
- Review and manage beneficiary records
- Audit previously added payees



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

Create and manage reusable payee records for a specific user through the Paywint Developer API.

The **Payee Management API** allows you to create and manage reusable recipient records for a specific Paywint user.

A **payee** represents the recipient identity referenced during payment creation.\
This API manages recipient records.

***

## What This API Provides

The Payee API enables your integration to:

* Create a reusable payee tied to a specific user
* Store at least one verified contact method (email or phone with country code)
* Retrieve a payee by ID
* List all payees associated with a user (paginated)
* Update payee details
* Delete unused payees

Each payee must include:

* `name` (recipient display name)
* At least one contact method

An optional `metadata` field may be used to store application-specific reference data.

***

## Available APIs

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

  <Card title="Update Payee" icon="pencil" href="/api-reference/payees/update">
    Modify the payee name or associated metadata.
  </Card>

  <Card title="Get Payee" icon="user" href="/api-reference/payees/get">
    Retrieve a specific payee by ID.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="List Payees" icon="list" href="/api-reference/payees/list">
    Retrieve all payees associated with a user.
  </Card>

  <Card title="Delete Payee" icon="trash" href="/api-reference/payees/delete">
    Remove an existing payee record.
  </Card>
</CardGroup>

***

## Typical Integration Flow

<Steps>
  <Step title="1. Create a payee">
    Call <code>[Create Payee](/api-reference/payees/create)</code> with the user ID, name, and contact details.
  </Step>

  <Step title="2. Store the payee ID">
    Persist the returned `payee_id` in your system for future transactions.
  </Step>

  <Step title="3. Reference the payee during payment creation">
    Provide the `payee_id` when calling payment endpoints.
  </Step>

  <Step title="4. Maintain payee accuracy">
    Update or delete payees as recipient information changes.
  </Step>
</Steps>

***

## Best Practices

* Validate email and phone format before submission.
* Avoid creating duplicate payees when an existing record can be reused.


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

PUT /api/user-api/payee/update
Update the display name of an existing payee.

This endpoint allows you to:
- Correct a payee’s name
- Align beneficiary records with accounting systems

Only the stored payee name is updated. The payee identity remains unchanged.



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

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

This endpoint performs the following actions:
- Authenticates the developer using `X-Api-Key` and `X-Api-Secret`
- 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

The returned token must be supplied on all SDK-facing calls as:



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

POST /api/user-api/payment/create-payment-link
Generates a secure payment link to collect wallet-based payments from customers or external users.

This endpoint:
- Creates a new pending payment request for the 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://docs.paywint.com/api-reference/payment/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/payment/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://docs.paywint.com/api-reference/payment/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/payment/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](/webhook) documentation.
      </Step>

      <Step title="Redirect the customer">
        After the checkout finishes, Paywint redirects the customer to the **Redirect URL**\
        that you configure in your developer 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/payment/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](/webhook) 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 developer 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/payment/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/payment/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](/webhook) documentation for
        all available event types and payload shapes.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Get Payment
Source: https://docs.paywint.com/api-reference/payment/get-payment

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

This endpoint:

- Retrieves a payment record by its id
- Returns payer/payee information, amount, and payment status



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

POST /api/user-api/payment/list/payment-received
Get a list of all payments received by your account.

This endpoint:
- Returns all incoming payments along with payer details



# List Sent Payments
Source: https://docs.paywint.com/api-reference/payment/list-sent-payments

POST /api/user-api/payment/list/payment-send
Get a list of all payments sent from your account.

This endpoint:
- Returns all outgoing payments along with recipient details



# Overview
Source: https://docs.paywint.com/api-reference/payment/overview

Create and manage wallet-based payment transactions through the Paywint Developer API.

The **Payment API** allows you to create and retrieve payment transactions associated with your account.

This API enables:

* Creating payment links to collect funds
* Retrieving individual payment details
* Listing outgoing payments
* Listing incoming paymentsd

***

## What This API Provides

The Payment API allows your integration to:

* Generate secure payment links for wallet-based collections
* Retrieve a payment record by its unique identifier
* List payments sent from the user account
* List payments received into the user account

Each payment record includes:

* Unique payment ID
* Amount (USD)
* Payment status
* Payer and payee details
* Timestamps
* System-generated metadata

***

## Available APIs

<CardGroup>
  <Card title="Create Payment Link" icon="link" href="/api-reference/payment/create-payment">
    Generate a secure payment link to collect funds.
  </Card>

  <Card title="Get Payment" icon="search" href="/api-reference/payment/get-payment">
    Retrieve a specific payment using its ID.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="List Sent Payments" icon="arrow-up-right" href="/api-reference/payment/list-sent-payments">
    Retrieve all outgoing payments from the user account.
  </Card>

  <Card title="List Received Payments" icon="arrow-down-left" href="/api-reference/payment/list-received-payments">
    Retrieve all incoming payments to the user account.
  </Card>
</CardGroup>

***

## Typical Integration Flow

<Steps>
  <Step title="1. Create a payment link">
    Call <code>Create Payment</code> with the amount and optional description to generate a shareable payment URL.
  </Step>

  <Step title="2. Share the payment link">
    Send the generated URL to the payer for completion.
  </Step>

  <Step title="3. Track payment status">
    Use <code>Get Payment</code> to retrieve transaction details and monitor status updates.
  </Step>

  <Step title="4. Reconcile transactions">
    Use <code>List Sent Payments</code> and <code>List Received Payments</code> for reporting and reconciliation.
  </Step>
</Steps>

***

## Pagination

The list endpoints require:

* `rows_per_page` (10, 20, 50, or 100)
* `page_no` (starting from 1)

Responses include:

* `records`
* `totalRecords`
* `queryGeneratedTime`

Use pagination to efficiently handle large transaction volumes.

***

## Best Practices

* Always validate amounts before submission.
* Store the returned `payment_id` for reconciliation and status tracking.
* Use `Get Payment` to confirm final transaction state.
* Implement proper pagination handling for production environments.
* Securely store API credentials and never expose them client-side.


# Get Paywint Card
Source: https://docs.paywint.com/api-reference/paywint-cards/get-card

GET /api/user-api/card/payee/pw-card/issued/{request_id}
Fetches a specific Payee's Paywint Card request by its unique request ID.

This endpoint retrieves the details of a specific paywint card request issued by the authenticated account,
including associated card details when available (for approved requests).

If the paywint card has been approved, the last 4 digits of the card number will be included (masked with leading `**`).

Parameters:
- `request_id`: The unique identifier for the Paywint Card request to fetch.

Returns:
- Full details of the requested paywint card, including status, linked card information (if applicable), and other related details.



# Issue Paywint Card For Payee
Source: https://docs.paywint.com/api-reference/paywint-cards/issue-card

POST /api/user-api/card/payee/pw-card/request
Issues and funds a Paywint Card for a payee.

This endpoint performs the following operations:

- Verifies that the payee exists.
- Confirms the payee has a default address set.
- Validates that the issuing account's Paywint wallet has sufficient available balance.
- Deducts the initial load amount from the issuing account's wallet.
- Creates the paywint card request associated with the payee.

Prerequisites:

- The payee must be created using the Create Payee endpoint.
- A default address must be set using either the Create Payee Address or Set Default Payee Address endpoint.
- The default address is used as the billing address for the issued paywint card.

Requirements:

- `amount` is required.
- Minimum initial load amount is $2.00.
- `card_nickname` is optional.
- If `card_nickname` is not provided, the default value "My Paywint Card" will be used.

The initial load amount is immediately deducted from the issuing account’s available wallet balance at the time of the request.

Returns the created paywint card request.



# List Paywint Cards
Source: https://docs.paywint.com/api-reference/paywint-cards/list-cards

GET /api/user-api/card/payee/pw-card/issued
Returns a list of Payee's Paywint Cards issued by the user.

This endpoint retrieves all paywint card requests created by the issuing account,
including associated card details when available.

For approved paywint card requests, the last 4 digits of the card number are provided
in the response, with leading `**` to mask the full number. Example: `**1234`.

Each record includes:

- Payee's paywint card request information
- Current status
- Initial funded amount
- Payee details
- Linked card details (if approved)



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

Issue, retrieve, and manage Paywint cards for payees.

Paywint cards let you deliver spend-ready balances to payees without handling sensitive card data.

***

## Prerequisites

1. Create the payee profile by following <code>[Create Payee](/api-reference/payees/create)</code>.
2. Add at least one address for that payee via <code>[Create Payee Address](/api-reference/payees/address/create-address)</code> so Paywint can route and track the delivery.

***

## Paywint card capabilities

You can:

* Issue a new Paywint card for a payee with a specified amount and currency.
* Retrieve the full Paywint card payload (numbers, expiration, status flags) using the issued `request_id`.
* List every Paywint card that you have issued.
* Reload an existing Paywint card to add more funds when the card still needs a top-up.

***

## How the Paywint card flow works

<Steps>
  <Step title="1. Request a new card">
    Call <code>[Issue Paywint Card For Payee](/api-reference/paywint-cards/issue-card)</code> with the payee identity, amount, currency, and any metadata that ties the card back to your system.
  </Step>

  <Step title="2. Deliver card details">
    The response includes a `request_id` and the encrypted card payload. Store the `request_id` and share the payload with the payee through your secure channels.
  </Step>

  <Step title="3. Track card status">
    Use <code>[List Paywint Cards](/api-reference/paywint-cards/list-cards)</code> to see every card for the user, or call <code>[Get Paywint Card](/api-reference/paywint-cards/get-card)</code> when you need the latest metadata for a specific issuance.
  </Step>

  <Step title="4. Reload when needed">
    If the card needs more value, call <code>[Reload Paywint Card](/api-reference/paywint-cards/reload-card)</code> to top it up without issuing a new card.
  </Step>
</Steps>

***

## Available APIs

<CardGroup>
  <Card title="Issue Paywint Card" href="/api-reference/paywint-cards/issue-card" icon="plus">
    Generate a Paywint card for a given payee and amount.
  </Card>

  <Card title="Get Paywint Card" href="/api-reference/paywint-cards/get-card" icon="credit-card">
    Retrieve the issued card payload using the `request_id`.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="List Paywint Cards" href="/api-reference/paywint-cards/list-cards" icon="list">
    List every Paywint card associated with a user to monitor outstanding balances.
  </Card>

  <Card title="Reload Paywint Card" href="/api-reference/paywint-cards/reload-card" icon="refresh">
    Add value to an existing Paywint card when the balance needs replenishing.
  </Card>
</CardGroup>

***

## Best practices

* Treat the `request_id` as the canonical reference for every Paywint card issuance.
* Share card details with payees securely, then delete or mask raw values on your end.
* Call `List Paywint Cards` regularly to reconcile what your system issued versus what remains outstanding.
* Use the reload API only when your compliance rules allow topping up previously issued cards.


# Reload Paywint Card
Source: https://docs.paywint.com/api-reference/paywint-cards/reload-card

POST /api/user-api/card/payee/pw-card/reload
Reloads (top-ups) an issued Paywint Card by deducting funds directly from the issuer’s Paywint wallet balance.

The provided `payee_card_id` identifies the issued card, and the specified `amount` is debited from the wallet's available balance and applied to the card through the Paywint recharge flow.

The wallet must have sufficient available balance for the reload to succeed.



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

GET /api/user-api/wallet/get
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://docs.paywint.com/api-reference/wallet/overview

Retrieve wallet balance information for a specific user.

The **Wallet API** allows you to retrieve wallet information associated with a specific Paywint user.

This API provides balance visibility and wallet metadata.
If a wallet does not already exist for the user, it is automatically created when this endpoint is called.

***

## What This API Provides

The Wallet API enables your integration to:

* Retrieve wallet balance information
* View current and available balances
* Access wallet metadata
* Ensure a wallet exists for the user

The response includes:

* Current balance
* Available balance
* Wallet identifiers
* System-generated metadata
* Query timestamp

All balances are returned in USD unless otherwise configured for your account.

***

## Balance Definitions

| Field             | Description                                |
| ----------------- | ------------------------------------------ |
| Current Balance   | Total funds recorded in the wallet.        |
| Available Balance | Funds available for withdrawal or payment. |

## Available API

<CardGroup>
  <Card title="Get Wallet" icon="wallet" href="/api-reference/wallet/get-wallet">
    Retrieve wallet balance and metadata for a user.
  </Card>
</CardGroup>

***

## Typical Integration Flow

<Steps>
  <Step title="1. Retrieve wallet information">
    Call <code>Get Wallet</code> to obtain the user's current and available balances.
  </Step>

  <Step title="2. Validate available balance">
    Ensure sufficient available funds before creating a payment or transfer.
  </Step>

  <Step title="3. Display balance in your application">
    Use the returned balance values to update dashboards or account summaries.
  </Step>
</Steps>

***

## Best Practices

* Always check the available balance before initiating a transaction.
* Do not rely solely on cached balance values for critical payment decisions.
* Use server-side validation when enforcing balance requirements.
* Secure API credentials and avoid exposing them in client-side code.


# Authentication
Source: https://docs.paywint.com/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-Api-Key`, and  `X-Api-Secret`.

```curl Example Api Call theme={null}
curl -X POST "https://<environment>/api/example" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -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.

***

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


# Dashboards
Source: https://docs.paywint.com/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.app.paywint.com">
    For testing and development purposes. Use this dashboard to simulate transactions and integrations in a safe environment.

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

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

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


# Environments
Source: https://docs.paywint.com/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.app.paywint.com).
3. Navigate to the [Credentials tab](https://sandbox.app.paywint.com/app/developer-panel/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://app.paywint.com).
3. Navigate to the [Credentials tab](https://app.paywint.com/app/developer-panel/api-credentials) to obtain your production API key.
4. Set the API base URL to: `https://api.paywint.com`


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

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="/environments">
    Accelerate your development cycle using Paywint’s separate environments for testing and live deployment.
  </Card>

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

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

  <Card title="Webhooks" icon="wifi" href="/webhook">
    Learn how to receive and handle Paywint webhook events.
  </Card>
</CardGroup>


# Customise Redirect Behaviour
Source: https://docs.paywint.com/redirect

Display a confirmation page with your customer's order information.

When someone makes a payment using Paywint Checkout, they are taken to Paywint’s secure checkout page.
After the payment attempt is finished—whether it succeeds or fails—Paywint automatically **redirects the customer back to your website**.

It’s how your site knows the result of the payment so you can show the appropriate message.

***

## How It Works

1. Your customer clicks “Pay” in your app or website.
2. Paywint opens its secure checkout page.
3. The customer chooses a payment method and completes the process.
4. When the payment finishes, Paywint **redirects the customer back to the page you chose** (your Redirect URL”).
5. Paywint adds two small pieces of information to the web address when sending them back:

   * `id`: the unique Paywint payment number
   * `status`: the result of the payment (`success`, `failed`, or `rejected`)

That’s it—the customer is now back on your site, and you know what happened with their payment.

***

## Example Redirects

After a payment, Paywint might send the customer back to your site like this:

```text theme={null}
https://yourapp.com/checkout/result?status=success&id=pay_9f3a2c
https://yourapp.com/checkout/result?status=failed&id=pay_9f3a2c
```

Notice the extra `id` and `status` at the end of the web address. You can use these values to decide what message to show your customer.

***

## What the Status Means

| Status    | What it means for the payment   | What you might show your customer               |
| --------- | ------------------------------- | ----------------------------------------------- |
| `success` | The payment went through.       | “Payment successful! Thank you for your order.” |
| `failed`  | The payment did not go through. | “Something went wrong. Please try again.”       |

> Some payment methods may initially display a processing status. This means the final result will be available later. In such cases, your system should wait for confirmation—either through a webhook or by checking the payment details in Paywint.

***

## Where to Setup

You decide the page where customers should land after payment. This is called your **Redirect URL**.

### Sandbox

Use the **Sandbox environment** to test your redirect behavior before moving to production.

1. **Create a Sandbox Account:**\
   Sign up for a [Sandbox Account](https://sandbox.app.paywint.com) to start testing your integration.

2. **Get API Key:**\
   Go to the [Developer Panel → API Key](https://sandbox.app.paywint.com/app/developer-panel/api-credentials) section to generate your Sandbox API key.

3. **Configure Redirect URLs:**\
   In the [Developer Panel → Redirect/Webhook](https://sandbox.app.paywint.com/app/developer-panel/urls) section, you’ll find fields to enter your test endpoints:
   * **Payment Redirect URL:**\
     The endpoint to which redirects happen when a specific payment action completes.\
     Example: `https://example.com/Redirect/payment`

### Production

Once your Sandbox testing is complete, you can move to the **Production environment**.

Before enabling your Production setup, please contact our [support team](https://paywint.com/contact) to ensure your API and redirect configurations are properly activated.

1. **Create a Production Account:**\
   Sign up for a [Production Account](https://app.paywint.com).

2. **Enable Production Access:**\
   Contact our [support team](https://paywint.com/contact) to request activation of your Production API and redirect setup.

3. **Get API Key:**\
   Go to the [Developer Panel → API Keys](https://app.paywint.com/app/developer-panel/api-credentials) section to obtain your Production API key.

4. **Set Your Redirect URL:**\
   In the [Developer Panel → Redirect/Webhook](https://app.paywint.com/app/developer-panel/urls) section, enter your live redirect endpoint.\
   Example: `https://yourapp.com/checkout/payment`

5. **Support Contacts:**\
   If you need assistance during setup:

* **Email:** [support@paywint.com](mailto:support@paywint.com)
* **Phone:** [+1 (408) 461-5543](tel:+14084615543)
* **Live Chat:** Available via the Paywint Dashboard

***

## Why This Matters

* Redirects allow customers to **return to your app smoothly** after completing a payment.
* You can immediately display a confirmation page showing whether the payment was successful, failed, or rejected.
* To ensure complete accuracy, your system should also verify the final result through Paywint’s webhook or by retrieving the payment details.

***

## Quick Setup

1. In [Developer Panel → Redirect/Webhook](https://app.paywint.com/app/developer-panel/urls), set your **Payment Redirect URL** (the page where customers should land after payment).
2. Make sure this page can read the `status` and `id` from the web address.
3. Show your customer the right message based on the result.

That’s all—your customers always end up back in your app, and you can guide them to their next step.


# Webhooks
Source: https://docs.paywint.com/webhook

Learn how to receive and handle Paywint webhook events.

## Overview

This page explains how to set up and use webhooks.

To begin, you must configure a single URL endpoint that will receive `POST` requests. This endpoint should be hosted on a server you control and be capable of processing incoming webhook payloads.

All webhook events—such as `initiated`, `processing`, `success`, `failed`, and `rejected`—will be sent to the configured URL.

***

## Where To Setup

### Sandbox

Use the **Sandbox environment** to test your webhook setup before moving to production.

1. **Create a Sandbox Account:**\
   Sign up for a [Sandbox Account](https://sandbox.app.paywint.com) to start testing your integration.

2. **Get API Key:**\
   Go to the [Developer Panel → API Key](https://sandbox.app.paywint.com/app/developer-panel/api-credentials) section to generate your Sandbox API key.

3. **Configure Webhook URLs:**\
   In the [Developer Panel → Redirect/Webhook](https://sandbox.app.paywint.com/app/developer-panel/urls) section, you’ll find fields to enter your test endpoint:
   * **Webhook URL:**\
     The endpoint that receives specific event webhooks for payment status updates (e.g., `payment.success`, `payment.failed`).\
     Example: `https://example.com/webhook`

### Production

Once your Sandbox testing is complete, you can move to the **Production environment**.

Before enabling your Production setup, please contact our [support team](https://paywint.com/contact) to ensure your API and webhook configurations are properly activated.

1. **Create a Production Account:**\
   Sign up for a [Production Account](https://app.paywint.com).

2. **Enable Production Access:**\
   Contact our [support team](https://paywint.com/contact) to request activation of your Production API and webhook setup.

3. **Get API Key:**\
   Go to the [Developer Panel → API Keys](https://app.paywint.com/app/developer-panel/api-credentials) section to obtain your Production API key.

4. **Configure Webhook URLs:**
   In the [Developer Panel → Redirect/Webhook](https://app.paywint.com/app/developer-panel/urls) section, enter your live endpoint:

* **Webhook URL:**\
  The live endpoint that receives real-time payment event webhooks.\
  Example: `https://yourapp.com/webhook`

5. **Support Contacts:**\
   If you need assistance during setup:

* **Email:** [support@paywint.com](mailto:support@paywint.com)
* **Phone:** [+1 (408) 461-5543](tel:+14084615543)
* **Live Chat:** Available via the Paywint Dashboard

***

## Webhook Events

Below is the list of webhook events sent by Paywint.

| Event Name           | Description                              |
| -------------------- | ---------------------------------------- |
| `payment.initiated`  | Payment was initiated.                   |
| `payment.processing` | Payment is being processed.              |
| `payment.success`    | Payment was successful.                  |
| `payment.failed`     | Payment failed.                          |
| `payment.rejected`   | Payment was rejected.                    |
| `payment.retried`    | Payment was retried with new payment ID. |
| `payment.opened`     | Payment link was opened by the user.     |
| `payment.expired`    | Payment link has been expired.           |

***

## Basic Structure

| Field                | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `event`              | The type of event that occurred (e.g., `payment.success`). |
| `id`                 | A unique identifier for this webhook delivery.             |
| `data`               | The event-specific payload object.                         |
| `eventGeneratedTime` | UNIX timestamp (in seconds) when the event was generated.  |

Example payload:

```json theme={null}
{
  "event": "payment.success",
  "id": "a891bfc2-ffff-464b-89e4-xxxxx",
  "data": {
    "payment_id": "b91a0f36-b10b-4a31-ae12-e8b4c5ee71f4",
    "status": "success",
    "amount": 599
  },
  "eventGeneratedTime": 1718006400.0
}
```

***

## Delivery & Retry Behavior

If your webhook endpoint fails to return a `2xx` HTTP response, Paywint will automatically retry delivery up to **two more times**, for a total of **three attempts** per event.

* Retries are sent within a predefined timeframe.
* If all three attempts fail, Paywint will notify your **email** with details of the failed event.

> **Note:** To avoid missed events, ensure your webhook endpoint is highly available and returns `200 OK` quickly. Any internal processing should happen asynchronously to avoid missed events.

***

## Detailed Webhook Responses

For complete webhook payload examples and detailed field descriptions for each event type, see our [Webhook Responses](/webhook-response) documentation page.

<Card title="Webhook Responses" icon="code" href="/webhook-response">
  View detailed webhook payload examples, field descriptions, and implementation guidance for all payment events.
</Card>


# Webhook Responses
Source: https://docs.paywint.com/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>