Send Physical Check Payment

curl --request POST \
  --url https://api.paywint.com/api/platform/payment/mail-check/{user_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Platform-ID: <x-platform-id>' \
  --header 'X-Signature: <x-signature>' \
  --data '
{
  "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
  "amount": 150,
  "payee_address_id": "f47ac10b-****-****-****-0e02b2c3d479",
  "invoice_no": "INV-2024-001234",
  "description": "Payment for consulting services",
  "mail_type": "USPS_FIRST_CLASS",
  "payment_method": "WALLET",
  "remittance": [
    {
      "id": "INV-001",
      "date": "09-15-2025",
      "amount": 150,
      "gross": 150,
      "discount": 10,
      "description": "Consulting services - September 2025"
    }
  ],
  "attachment_url": "https://example.com/documents/invoice.pdf"
}
'

import requests

url = "https://api.paywint.com/api/platform/payment/mail-check/{user_id}"

payload = {
    "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "amount": 150,
    "payee_address_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "invoice_no": "INV-2024-001234",
    "description": "Payment for consulting services",
    "mail_type": "USPS_FIRST_CLASS",
    "payment_method": "WALLET",
    "remittance": [
        {
            "id": "INV-001",
            "date": "09-15-2025",
            "amount": 150,
            "gross": 150,
            "discount": 10,
            "description": "Consulting services - September 2025"
        }
    ],
    "attachment_url": "https://example.com/documents/invoice.pdf"
}
headers = {
    "X-Platform-ID": "<x-platform-id>",
    "X-Signature": "<x-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Platform-ID': '<x-platform-id>',
    'X-Signature': '<x-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payee_id: 'f47ac10b-****-****-****-0e02b2c3d479',
    amount: 150,
    payee_address_id: 'f47ac10b-****-****-****-0e02b2c3d479',
    invoice_no: 'INV-2024-001234',
    description: 'Payment for consulting services',
    mail_type: 'USPS_FIRST_CLASS',
    payment_method: 'WALLET',
    remittance: [
      {
        id: 'INV-001',
        date: '09-15-2025',
        amount: 150,
        gross: 150,
        discount: 10,
        description: 'Consulting services - September 2025'
      }
    ],
    attachment_url: 'https://example.com/documents/invoice.pdf'
  })
};

fetch('https://api.paywint.com/api/platform/payment/mail-check/{user_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paywint.com/api/platform/payment/mail-check/{user_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payee_id' => 'f47ac10b-****-****-****-0e02b2c3d479',
    'amount' => 150,
    'payee_address_id' => 'f47ac10b-****-****-****-0e02b2c3d479',
    'invoice_no' => 'INV-2024-001234',
    'description' => 'Payment for consulting services',
    'mail_type' => 'USPS_FIRST_CLASS',
    'payment_method' => 'WALLET',
    'remittance' => [
        [
                'id' => 'INV-001',
                'date' => '09-15-2025',
                'amount' => 150,
                'gross' => 150,
                'discount' => 10,
                'description' => 'Consulting services - September 2025'
        ]
    ],
    'attachment_url' => 'https://example.com/documents/invoice.pdf'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Platform-ID: <x-platform-id>",
    "X-Signature: <x-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paywint.com/api/platform/payment/mail-check/{user_id}"

	payload := strings.NewReader("{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Platform-ID", "<x-platform-id>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paywint.com/api/platform/payment/mail-check/{user_id}")
  .header("X-Platform-ID", "<x-platform-id>")
  .header("X-Signature", "<x-signature>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paywint.com/api/platform/payment/mail-check/{user_id}")

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

request = Net::HTTP::Post.new(url)
request["X-Platform-ID"] = '<x-platform-id>'
request["X-Signature"] = '<x-signature>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Operation completed.",
  "data": {
    "payment_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "transaction_id": 1501,
    "payer_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "amount": 100,
    "processing_fee": 1.5,
    "delivery_fee": 0.5,
    "invoice_no": "INV-2024-001234",
    "currency": "USD",
    "description": "June invoice for services",
    "created_at": "2025-06-16T10:04:51.739761Z",
    "payment_date": "2025-06-16T10:13:16.749655Z",
    "status": "success",
    "card_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_card_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "to_pw_bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "failure_reason": "Insufficient wallet balance",
    "payout_currency": "INR",
    "payout_amount": 8500,
    "exchange_rate": 84.91,
    "payment_method": "WALLET",
    "receiving_method": "CHECK_MAIL",
    "attachment_url": "https://paywint-bucket.s3.amazonaws.com/wallet/check-payments/23ec826b-54cd-4241-a855-ae038bbf568a/testing.pdf"
  },
  "queryGeneratedTime": 1718006400
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Mail Check

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.

POST

api

platform

payment

mail-check

{user_id}

Send Physical Check Payment

curl --request POST \
  --url https://api.paywint.com/api/platform/payment/mail-check/{user_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Platform-ID: <x-platform-id>' \
  --header 'X-Signature: <x-signature>' \
  --data '
{
  "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
  "amount": 150,
  "payee_address_id": "f47ac10b-****-****-****-0e02b2c3d479",
  "invoice_no": "INV-2024-001234",
  "description": "Payment for consulting services",
  "mail_type": "USPS_FIRST_CLASS",
  "payment_method": "WALLET",
  "remittance": [
    {
      "id": "INV-001",
      "date": "09-15-2025",
      "amount": 150,
      "gross": 150,
      "discount": 10,
      "description": "Consulting services - September 2025"
    }
  ],
  "attachment_url": "https://example.com/documents/invoice.pdf"
}
'

import requests

url = "https://api.paywint.com/api/platform/payment/mail-check/{user_id}"

payload = {
    "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "amount": 150,
    "payee_address_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "invoice_no": "INV-2024-001234",
    "description": "Payment for consulting services",
    "mail_type": "USPS_FIRST_CLASS",
    "payment_method": "WALLET",
    "remittance": [
        {
            "id": "INV-001",
            "date": "09-15-2025",
            "amount": 150,
            "gross": 150,
            "discount": 10,
            "description": "Consulting services - September 2025"
        }
    ],
    "attachment_url": "https://example.com/documents/invoice.pdf"
}
headers = {
    "X-Platform-ID": "<x-platform-id>",
    "X-Signature": "<x-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Platform-ID': '<x-platform-id>',
    'X-Signature': '<x-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payee_id: 'f47ac10b-****-****-****-0e02b2c3d479',
    amount: 150,
    payee_address_id: 'f47ac10b-****-****-****-0e02b2c3d479',
    invoice_no: 'INV-2024-001234',
    description: 'Payment for consulting services',
    mail_type: 'USPS_FIRST_CLASS',
    payment_method: 'WALLET',
    remittance: [
      {
        id: 'INV-001',
        date: '09-15-2025',
        amount: 150,
        gross: 150,
        discount: 10,
        description: 'Consulting services - September 2025'
      }
    ],
    attachment_url: 'https://example.com/documents/invoice.pdf'
  })
};

fetch('https://api.paywint.com/api/platform/payment/mail-check/{user_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paywint.com/api/platform/payment/mail-check/{user_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payee_id' => 'f47ac10b-****-****-****-0e02b2c3d479',
    'amount' => 150,
    'payee_address_id' => 'f47ac10b-****-****-****-0e02b2c3d479',
    'invoice_no' => 'INV-2024-001234',
    'description' => 'Payment for consulting services',
    'mail_type' => 'USPS_FIRST_CLASS',
    'payment_method' => 'WALLET',
    'remittance' => [
        [
                'id' => 'INV-001',
                'date' => '09-15-2025',
                'amount' => 150,
                'gross' => 150,
                'discount' => 10,
                'description' => 'Consulting services - September 2025'
        ]
    ],
    'attachment_url' => 'https://example.com/documents/invoice.pdf'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Platform-ID: <x-platform-id>",
    "X-Signature: <x-signature>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paywint.com/api/platform/payment/mail-check/{user_id}"

	payload := strings.NewReader("{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Platform-ID", "<x-platform-id>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paywint.com/api/platform/payment/mail-check/{user_id}")
  .header("X-Platform-ID", "<x-platform-id>")
  .header("X-Signature", "<x-signature>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paywint.com/api/platform/payment/mail-check/{user_id}")

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

request = Net::HTTP::Post.new(url)
request["X-Platform-ID"] = '<x-platform-id>'
request["X-Signature"] = '<x-signature>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payee_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"amount\": 150,\n  \"payee_address_id\": \"f47ac10b-****-****-****-0e02b2c3d479\",\n  \"invoice_no\": \"INV-2024-001234\",\n  \"description\": \"Payment for consulting services\",\n  \"mail_type\": \"USPS_FIRST_CLASS\",\n  \"payment_method\": \"WALLET\",\n  \"remittance\": [\n    {\n      \"id\": \"INV-001\",\n      \"date\": \"09-15-2025\",\n      \"amount\": 150,\n      \"gross\": 150,\n      \"discount\": 10,\n      \"description\": \"Consulting services - September 2025\"\n    }\n  ],\n  \"attachment_url\": \"https://example.com/documents/invoice.pdf\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Operation completed.",
  "data": {
    "payment_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "transaction_id": 1501,
    "payer_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "amount": 100,
    "processing_fee": 1.5,
    "delivery_fee": 0.5,
    "invoice_no": "INV-2024-001234",
    "currency": "USD",
    "description": "June invoice for services",
    "created_at": "2025-06-16T10:04:51.739761Z",
    "payment_date": "2025-06-16T10:13:16.749655Z",
    "status": "success",
    "card_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_card_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "payee_bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "to_pw_bank_id": "f47ac10b-****-****-****-0e02b2c3d479",
    "failure_reason": "Insufficient wallet balance",
    "payout_currency": "INR",
    "payout_amount": 8500,
    "exchange_rate": 84.91,
    "payment_method": "WALLET",
    "receiving_method": "CHECK_MAIL",
    "attachment_url": "https://paywint-bucket.s3.amazonaws.com/wallet/check-payments/23ec826b-54cd-4241-a855-ae038bbf568a/testing.pdf"
  },
  "queryGeneratedTime": 1718006400
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Headers

X-Platform-ID

string<uuid>

required

Unique platform identifier (UUID). You receive this during onboarding. Must be sent with every API request.

X-Signature

string

required

HMAC-SHA256 request signature for authentication. Use your platform secret key to compute it as: METHOD + PATH + QUERY + BODY_HASH.

Path Parameters

user_id

string<uuid>

required

Unique identifier (UUID) of the user who mails the check.

Body

application/json

payee_id

string<uuid4>

required

Unique identifier (UUID) of the recipient who will receive the physical check.

Example:

"f47ac10b-****-****-****-0e02b2c3d479"

amount

number

required

Payment amount in USD. Must be at least $1.00.

Required range: x >= 1

Example:

150

payee_address_id

string<uuid4>

required

UUID of the recipient's mailing address where the physical check will be sent.

Example:

"f47ac10b-****-****-****-0e02b2c3d479"

invoice_no

string | null

Invoice or reference number that will appear on the check for tracking purposes.

Maximum string length: 20

Example:

"INV-2024-001234"

description

string | null

Optional memo or description that will appear on the check.

Maximum string length: 255

Example:

"Payment for consulting services"

mail_type

enum<string>

default:USPS_FIRST_CLASS

Delivery method for the physical check. Options: USPS_FIRST_CLASS (default), USPS_CERTIFIED, OVERNIGHT, TWO_DAY. Different mail types have different processing fees.

Available options:

USPS_FIRST_CLASS,

USPS_CERTIFIED,

TWO_DAY,

OVERNIGHT

Example:

"USPS_FIRST_CLASS"

payment_method

enum<string>

default:WALLET

Payment source for the check amount and fees. Currently only WALLET is supported.

Available options:

WALLET

Example:

"WALLET"

remittance

RemittanceAdvice · object[] | null

Optional list of remittance details to include with the check (maximum 50 items). Useful for invoice breakdowns or payment details.

Show child attributes

attachment_url

string | null

Optional HTTPS URL of a PDF document to attach to the check. Must be a valid PDF, maximum 7MB, up to 10 pages. Additional fees apply per page.

Example:

"https://example.com/documents/invoice.pdf"

Response

Successful Response

success

boolean

default:true

Indicates whether the request was processed successfully.

Example:

true

message

string

default:Success

A short, human-readable message describing the result of the request.

Example:

"Operation completed."

data

ExternalCheckPaymentRead · object | null

The main response payload, if applicable

Show child attributes

queryGeneratedTime

number | null

default:1783679844.273462

The Unix timestamp (in seconds) indicating when the response was generated.

Example:

1718006400

Users

KYC & KYB

Wallet

Payments

Accept Payments

Cross Border Payments

Bank Accounts

Paywint Bank Accounts

Cards

Check

Payee Management

Payee Bank Accounts

Payee Cards

Payee Addresses

Mail Check

Headers

Path Parameters

Body

Response