{"info":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","description":"

Introduction

Welcome to the Payout API, your gateway to seamless, automated, and scalable payment solutions. Our API is engineered to empower developers and businesses to programmatically manage payouts. Our infrastructure provides the tools you need to create, track, and manage your payouts efficiently.

This document provides a comprehensive guide to our API, detailing its RESTful architecture, authentication methods, and available endpoints. Here, you will find all the information required to integrate our payout capabilities into your applications. We are committed to providing a clear, consistent, and developer-friendly experience to help you build with confidence.

Environments

Production: https://payouts.api.trykarat.com/

Sandbox: contact peter@trykarat.com to get sandbox information

API Keys

Generating and Managing API Keys

To use the Payout API, you will need an API key. You can generate and manage your API keys through your user dashboard. To access your API keys, navigate to the Settings page in your account.

From the settings page, you can:

Generate new API keys
\n
View your existing API keys
\n
Revoke API keys that are no longer needed
\n

API Key Storage Best Practices

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Here are some best practices for storing your API keys:

Store keys in environment variables: Do not hardcode your API keys in your application code. Instead, use environment variables and key vaults to store your keys and access them in your code.
\n
Limit access to keys: Only give access to your API keys to authorized personnel. Use a secret management service to store and manage your keys securely.
\n
Rotate keys regularly: We recommend rotating your API keys on a regular basis to reduce the risk of a compromised key being used.
\n

Revoking API Keys

If you suspect that an API key has been compromised, you should revoke it immediately from your user dashboard. Once an API key is revoked, it can no longer be used to make API requests.

Idempotency

Our API supports idempotency, which allows you to safely retry requests without accidentally performing the same operation twice. This is useful for cases where a request may have failed due to a network error, but you are unsure if the operation was successful.

This is particularly useful for POST requests that create new resources, as it prevents the creation of duplicate resources.

Sandbox Test Recipients

In the Sandbox environment, you can use predefined test recipient email addresses to simulate payout outcomes and error scenarios. This makes it easier to test your payout flows, webhook handling, and error recovery logic without creating real payouts.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Email	Target Status
`sandbox+completed@trykarat.com`	`completed`
`sandbox+failed@trykarat.com`	`failed`
`sandbox+returned@trykarat.com`	`returned`
`sandbox+canceled@trykarat.com`	`canceled`
`sandbox+pending@trykarat.com`	`pending`
`sandbox+created@trykarat.com`	`created`
`sandbox+awaiting_acceptance@trykarat.com`	`awaiting_acceptance`

These test recipients are especially useful for validating webhook notifications and ensuring your application handles each payout lifecycle state correctly.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Email	Simulated Error	HTTP Status
`sandbox+error_insufficient_funds@trykarat.com`	\"Insufficient funds to cover the payout batch\"	500
`sandbox+error_invalid_amount@trykarat.com`	\"All payout amounts must be greater than zero.\"	400

These scenarios can help you verify that your application properly handles validation failures and server-side errors.

Notes

These recipient emails work only in the Sandbox environment.
\n
Sandbox test recipients are intended for testing and should not be used in production.
\n
Status-based test recipients can be used together with your webhook configuration to validate event delivery and downstream processing.
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"19392455","collectionId":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","publishedId":"2sB3dLVsMR","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"8E81FF"},"publishDate":"2025-12-01T19:12:43.000Z"},"item":[{"name":"Payments","item":[{"name":"Get Payment By Id","id":"25acbaf0-65aa-4625-818a-961812427734","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/payments/:payment_id","description":"

This endpoint retrieves a single payment by its unique ID. This is useful for checking the status and details of a specific transaction. It also provides a payment link so you can share with you recipients.

This endpoint retrieves a list of payments, with support for pagination using the limit and offset query parameters. It is also possible to filter by recipient or/and batch

Number of objects to return

\n","type":"text/plain"},"key":"limit","value":"10"},{"disabled":true,"description":{"content":"

Offset number to return

\n","type":"text/plain"},"key":"offset","value":"0"},{"disabled":true,"description":{"content":"

List by specific recipient

\n","type":"text/plain"},"key":"recipientId","value":""},{"disabled":true,"description":{"content":"

List by specific batch

\n","type":"text/plain"},"key":"batchId","value":""}],"variable":[]}},"response":[{"id":"b4cec2d7-6092-4fd3-ac0f-61382446d9c1","name":"Get Payments","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {api_key}","type":"text"}],"url":{"raw":"https://payouts.api.trykarat.com/payments?limit=10&offset=0","protocol":"https","host":["payouts","api","trykarat","com"],"path":["payments"],"query":[{"key":"limit","value":"10","description":"Number of objects to return"},{"key":"offset","value":"0","description":"Offset number to return"},{"key":"recipientId","value":"e538056f-e1ec-47b5-91db-201f165d3286","description":"List by specific recipient","disabled":true},{"key":"batchId","value":"ea2a518f-7bee-47cf-be93-bbf939446924","description":"List by specific batch","disabled":true},{"key":"referenceId","value":"ea2a518f-7bee-47cf-be93-bbf939446924","type":"text","disabled":true}]}},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"b361beec-a466-409d-a7e2-0d3107b778dc\",\n \"amount\": 100000,\n \"description\": \"Payout 1\",\n \"statusUpdates\": [\n {\n \"id\": \"d6f90000-8ea4-4e86-ada7-ea762c4e9ca5\",\n \"status\": \"created\",\n \"reason\": null,\n \"date\": \"2025-11-28T19:50:34.422962+00:00\"\n }\n ],\n \"createdAt\": \"2025-11-28T19:50:34.422962+00:00\",\n \"recipient\": {\n \"id\": \"e538056f-e1ec-47b5-91db-201f165d3286\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\",\n \"autoAcceptPayouts\": null\n },\n \"payoutLink\": \"https://app.trykarat.com/signup?payout=b361beec-a466-409d-a7e2-0d3107b778dc\"\n },\n {\n \"id\": \"172293dc-7631-4fdd-bd18-1d1b085d1b21\",\n \"amount\": 100000,\n \"description\": \"Payout 2\",\n \"statusUpdates\": [\n {\n \"id\": \"1a6182a1-c7b0-4561-b2de-e4a7ae2addd3\",\n \"status\": \"created\",\n \"reason\": null,\n \"date\": \"2025-11-28T03:50:55.068791+00:00\"\n }\n ],\n \"createdAt\": \"2025-11-28T03:50:55.068791+00:00\",\n \"recipient\": {\n \"id\": \"e538056f-e1ec-47b5-91db-201f165d3286\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\",\n \"autoAcceptPayouts\": null\n },\n \"payoutLink\": \"https://app.trykarat.com/signup?payout=172293dc-7631-4fdd-bd18-1d1b085d1b21\"\n },\n {\n \"id\": \"01ffb945-c7b4-468b-8499-f9dcc6cadb19\",\n \"amount\": 100000,\n \"description\": \"\",\n \"statusUpdates\": [\n {\n \"id\": \"42996659-b8df-4fdb-8491-1ae218e449c4\",\n \"status\": \"created\",\n \"reason\": null,\n \"date\": \"2025-11-28T03:50:23.62208+00:00\"\n }\n ],\n \"createdAt\": \"2025-11-28T03:50:23.62208+00:00\",\n \"recipient\": {\n \"id\": \"e538056f-e1ec-47b5-91db-201f165d3286\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\",\n \"autoAcceptPayouts\": null\n },\n \"payoutLink\": \"https://app.trykarat.com/signup?payout=01ffb945-c7b4-468b-8499-f9dcc6cadb19\"\n }\n ],\n \"meta\": {\n \"total\": 3,\n \"limit\": 10,\n \"offset\": 0\n }\n}"}],"_postman_id":"88d1b232-ac21-4524-95b6-19a5157ace17"},{"name":"Create Payment Batch","id":"ad98179c-1936-4282-a836-d48cb8460caf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"payouts\": [\n {\n \"payeeEmail\": \"john+doe@trykarat.com\",\n \"description\": \"Your description\",\n \"amount\": 0\n }\n ],\n \"idempotencyKey\": \"any_unique_key\"\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/payments","description":"

This endpoint allows you to create a batch of one or more payments. You can use this to pay single or multiple recipients at once.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"bbe15c0b-cfa9-4968-90aa-bea85f893313","id":"bbe15c0b-cfa9-4968-90aa-bea85f893313","name":"Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["payments"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"c1204615-c768-4cf0-a401-1bd09e8603e2","name":"Create Batch with single payout","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"payouts\": [\n {\n \"payeeEmail\": \"example@mail.com\",\n \"description\": \"Payout 1\",\n \"amount\": 10000,\n \"referenceId\": \"93212f4a-39d9-40c7-97ca-2b9e69063944\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/payments"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"batchId\": \"30d6bb6e-5398-462c-a90c-7b9077f618d4\"\n \"payouts\": [\n {\n \"id\": \"0fc50d45-faa8-4d09-aa2a-a9ceb282d7ae\", \n \"payeeEmail\": \"example@mail.com\",\n \"description\": \"Payout 1\",\n \"amount\": 10000,\n \"referenceId\": \"93212f4a-39d9-40c7-97ca-2b9e69063944\"\n }\n ]\n }\n}"},{"id":"115203cd-537d-41d8-8cdf-ee7f0de32148","name":"Create Batch with multiple payouts","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {api_key}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"payouts\": [\n {\n \"payeeEmail\": \"example@trykarat.com\",\n \"description\": \"Payout 1\",\n \"amount\": 10000,\n \"referenceId\": \"8f4b2516-0c12-4df5-8d51-98831b997f97\"\n },\n {\n \"payeeEmail\": \"example2@trykarat.com\",\n \"amount\": 20000,\n \"referenceId\": \"23583813-8238-4e4f-8545-fd07261b3094\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/payments"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"batchId\": \"70624ae3-08db-40bc-817b-20e7cb264e46\",\n \"payouts\": [\n {\n \"id\": \"d65f87ee-04a5-455e-909c-67efc5a0ce63\",\n \"payeeEmail\": \"example@trykarat.com\",\n \"description\": \"Payout 1\",\n \"amount\": 10000,\n \"referenceId\": \"8f4b2516-0c12-4df5-8d51-98831b997f97\"\n },\n {\n \"id\": \"6ce6ca0a-31ff-4c74-89f0-87da19e8bb9d\",\n \"payeeEmail\": \"example2@trykarat.com\",\n \"amount\": 20000,\n \"referenceId\": \"23583813-8238-4e4f-8545-fd07261b3094\"\n }\n ]\n }\n}"}],"_postman_id":"ad98179c-1936-4282-a836-d48cb8460caf"},{"name":"Cancel Payment Intent","id":"2ac06e9a-bf0a-49d0-a8d0-8dcf10006482","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"url":"https://payouts.api.trykarat.com/payments/:payment_id/cancel","description":"

This endpoint cancels a payment that has not yet been accepted by the recipient. It can be used to cancel payments that weren't accepted by the recipient yet.

The Payments section provides endpoints for managing individual and batch payments.

This endpoint allows you to create a batch of one or more recipients. You can use this to add a single or multiple recipients at once.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}},"urlObject":{"protocol":"https","path":["recipients"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"7efd8da6-5fc3-4e5f-b9de-6d2f117f5f5a","name":"Add Recipients","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"recipients\": [\n {\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\"\n },\n {\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"email\": \"example2@mail.com\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/recipients"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"recipients\": [\n {\n \"id\": \"7eef1f23-b9e0-47b4-8a45-de66783e9426\",\n \"email\": \"example@mail.com\",\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"createdAt\": \"1764390414237\",\n \"onboardingUrl\": \"https://app.trykarat.com/signup?invitation=4e082a6a-fcff-4abe-a49d-3cac214bee63&payee=example%40mail.com\",\n \"status\": \"created\"\n },\n {\n \"id\": \"4c9bd313-e0bb-40d8-8521-f7bf01e87071\",\n \"email\": \"example2@mail.com\",\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"createdAt\": \"1764390414237\",\n \"onboardingUrl\": \"https://app.trykarat.com/signup?invitation=ba7257e6-f34c-455f-b02a-b99c5067aed6&payee=example2%40mail.com\",\n \"status\": \"created\"\n }\n ]\n }\n}"}],"_postman_id":"7cfa15c3-153f-4d0c-8cb3-474d490bdb36"},{"name":"Get Recipients","id":"64b7dbab-3370-4632-9593-b955fb4bb278","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/recipients?limit=10&offset=0","description":"

This endpoint retrieves a list of recipients, with support for pagination using the `limit` and `offset` query parameters.

Number of objects to return

\n","type":"text/plain"},"key":"limit","value":"10"},{"description":{"content":"

Offset number to return

\n","type":"text/plain"},"key":"offset","value":"0"}],"variable":[]}},"response":[{"id":"b5ab7e21-e5c0-43ba-aec0-c3ecffcab075","name":"Get Recipients","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://payouts.api.trykarat.com/recipients?limit=10&offset=0","protocol":"https","host":["payouts","api","trykarat","com"],"path":["recipients"],"query":[{"key":"limit","value":"10","description":"Number of objects to return"},{"key":"offset","value":"0","description":"Offset number to return"}]}},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"7eef1f23-b9e0-47b4-8a45-de66783e9426\",\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\",\n \"onboardingUrl\": \"https://app.trykarat.com/signup?invitation=4e082a6a-fcff-4abe-a49d-3cac214bee63&payee=example%40mail.com\",\n \"status\": \"created\"\n },\n {\n \"id\": \"4c9bd313-e0bb-40d8-8521-f7bf01e87071\",\n \"firstName\": \"Jhon\",\n \"lastName\": \"Doe\",\n \"email\": \"example2@mail.com\",\n \"onboardingUrl\": \"https://app.trykarat.com/signup?invitation=ba7257e6-f34c-455f-b02a-b99c5067aed6&payee=example%40mail.com\",\n \"status\": \"created\"\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"limit\": 10,\n \"offset\": 0\n }\n}"}],"_postman_id":"64b7dbab-3370-4632-9593-b955fb4bb278"},{"name":"Get Recipient By Id","id":"d7d647b4-b411-4089-b820-7b674f7e961b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/recipients/:recipient_id","description":"

This endpoint retrieves a single recipient by its unique ID. This is useful for checking the details of a specific recipient.

The Recipient section provides endpoints to add, list recipients and manage their details.

\n","_postman_id":"79157079-abf5-4be8-8372-3b498a0c0e48","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}}},{"name":"Tax","item":[{"name":"Get Recipient W9 Forms","id":"ac0fd528-582b-4171-a787-369e3c91faa9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/recipients/tax/:recipient_id","description":"

This endpoint provides a list of available tax forms for a specific recipient.

\n","urlObject":{"protocol":"https","path":["recipients","tax",":recipient_id"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[{"type":"any","value":"","key":"recipient_id"}]}},"response":[{"id":"4831bef2-8ceb-40a5-b4a9-d5f7f74f35c6","name":"Get Recipient W9 Forms","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://payouts.api.trykarat.com/recipients/tax/:recipient_id","protocol":"https","host":["payouts","api","trykarat","com"],"path":["recipients","tax",":recipient_id"],"variable":[{"key":"recipient_id","value":"89bf467-edfe-4cb5-802f-3e53f50fb4bc"}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"d2e664b0-ab07-4d5e-9297-40ee7a3d161d\",\n \"recipient\": {\n \"id\": \"189bf467-edfe-4cb5-802f-3e53f50fb4bc\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\"\n },\n \"createdAt\": \"2025-11-14T20:04:01.466286+00:00\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"limit\": 100,\n \"offset\": 0\n }\n}"}],"_postman_id":"ac0fd528-582b-4171-a787-369e3c91faa9"},{"name":"Get Recipient W9 Pdf Link","id":"ace20022-a945-4fac-b5ac-58028ededa0f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/recipients/tax/w9/:form_id/download","description":"

This endpoint retrieves a url to download a specific w9 pdf file based on it's unique ID.

\n","urlObject":{"protocol":"https","path":["recipients","tax","w9",":form_id","download"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[{"type":"any","value":"","key":"form_id"}]}},"response":[{"id":"1f410866-899b-42ea-9cc1-a3ca07068ced","name":"Get Recipient W9 Pdf Link","originalRequest":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/recipients/tax/w9/59682965-d106-48cb-8531-bc8e90adc6a5/download"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"url\": \"https://pdfdownloadlink.example/\"\n }\n}"}],"_postman_id":"ace20022-a945-4fac-b5ac-58028ededa0f"}],"id":"dca16aff-597f-4ad5-a64f-8ac992d225b2","description":"

The Tax section includes endpoints to list and get download url for tax documents.

\n","_postman_id":"dca16aff-597f-4ad5-a64f-8ac992d225b2","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}}},{"name":"External Payments","item":[{"name":"Get External Payment By Id","id":"377ea545-fde8-45ee-a3ee-59d525d0c07d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/external-payments/:external_payment_id","description":"

This endpoint retrieves a list of payments, with support for pagination using the limit and offset query parameters. It is also possible to filter by recipient or/and batch

Number of objects to return

\n","type":"text/plain"},"key":"limit","value":"10"},{"description":{"content":"

Offset number to return

\n","type":"text/plain"},"key":"offset","value":"0"},{"disabled":true,"description":{"content":"

List by specific recipient

\n","type":"text/plain"},"key":"recipientId","value":""},{"disabled":true,"description":{"content":"

List by specific batch

\n","type":"text/plain"},"key":"batchId","value":""}],"variable":[]}},"response":[{"id":"402f74ad-98d0-4748-8d3c-8484c7cf852d","name":"Get External Payments","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://payouts.api.trykarat.com/external-payments?limit=10&offset=0","protocol":"https","host":["payouts","api","trykarat","com"],"path":["external-payments"],"query":[{"key":"limit","value":"10","description":"Number of objects to return"},{"key":"offset","value":"0","description":"Offset number to return"},{"key":"recipientId","value":"","description":"List by specific recipient","type":"text","disabled":true},{"key":"batchId","value":"","description":"List by specific batch","type":"text","disabled":true}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"abd35a6a-21e6-4e85-b621-1abc28655932\",\n \"amount\": 15000,\n \"description\": \"Payout for video sponsorship\",\n \"date\": \"2026-01-29T00:00:00+00:00\",\n \"paymentMethod\": \"Venmo\",\n \"platform\": \"WISE\",\n \"createdAt\": \"2026-01-29T18:42:54.265662+00:00\",\n \"recipient\": {\n \"id\": \"e538056f-e1ec-47b5-91db-201f165d3286\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\"\n }\n },\n {\n \"id\": \"f9de7524-5504-42cd-9f9c-8a63e531d293\",\n \"amount\": 12000,\n \"description\": \"Affiliate revenue payout | Q1\",\n \"date\": \"2026-01-20T00:00:00+00:00\",\n \"paymentMethod\": \"ACH\",\n \"platform\": \"Chase Bank\",\n \"createdAt\": \"2026-01-29T18:42:54.265662+00:00\",\n \"recipient\": {\n \"id\": \"e538056f-e1ec-47b5-91db-201f165d3286\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"example@mail.com\"\n }\n }\n ],\n \"meta\": {\n \"total\": 2,\n \"limit\": 100,\n \"offset\": 0\n }\n}"}],"_postman_id":"b6cb5469-f527-4021-9f4e-41360208163e"},{"name":"Create External Payment Batch","id":"e54c5c66-84f5-4e25-9867-baec326f4ba4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"externalPayments\": [\n {\n \"recipientId\": \"4f8d5038-40e7-4dff-92ad-852cf326b612\",\n \"amount\": 15000,\n \"description\": \"Payout for video sponsorship\",\n \"date\": \"2024-01-24\",\n \"paymentMethod\": \"ACH\",\n \"platform\": \"instagram\"\n },\n {\n \"recipientId\": \"f3bd2878-10e3-44ed-b9ac-b81de673a7ec\",\n \"amount\": 342000,\n \"description\": \"Affiliate Campaign | Q1\",\n \"date\": \"2024-01-25\",\n \"paymentMethod\": \"WIRE\",\n \"platform\": \"twitch\"\n }\n ],\n \"idempotencyKey\": \"batch-1\"\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/external-payments","description":"

This endpoint allows you to create a batch of one or more payments. You can use this to pay single or multiple recipients at once.

This endpoint cancels a payment that has not yet been accepted by the recipient. It can be used to cancel payments that weren't accepted by the recipient yet.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"574be27a-e3bd-43f9-92d4-c9dd763696e6","id":"574be27a-e3bd-43f9-92d4-c9dd763696e6","name":"External Payments","type":"folder"}},"urlObject":{"protocol":"https","path":["external-payments",":external_payment_id"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[{"type":"any","value":"","key":"external_payment_id"}]}},"response":[{"id":"dec83b19-7caa-48fc-ad46-4f71d70f2dc1","name":"Patch External Payment","originalRequest":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 12000,\n \"description\": \"Brand collab | Q1\",\n \"date\": \"2025-01-20\",\n \"paymentMethod\": \"Wire\",\n \"platform\": \"Wise\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://payouts.api.trykarat.com/external-payments/:external_payment_id","protocol":"https","host":["payouts","api","trykarat","com"],"path":["external-payments",":external_payment_id"],"variable":[{"key":"external_payment_id","value":"f9de7524-5504-42cd-9f9c-8a63e531d293"}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"f9de7524-5504-42cd-9f9c-8a63e531d293\",\n \"success\": true\n }\n}"}],"_postman_id":"44ca3f58-7dd5-4a02-be0a-d6f646ce655f"},{"name":"Upload External Payment Receipt","id":"835015a1-2028-48c5-906a-7d8fe6d3b36e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":" {\n \"fileName\": \"receipt_example.pdf\",\n \"base64\": \"JVBERi0xLjMKJZOMi54gUmVwb3J0TGFiIEdlbmVyYXRlZCBQREYgZG9jdW1lbnQgaHR0cDovL3d3dy5yZXBvcnRsYWIuY29tCjEgMCBvYmoKPDwKL0YxIDIgMCBSCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9CYXNlRm9udCAvSGVsdmV0aWNhCi9FbmNvZGluZyAvV2luQW5zaUVuY29kaW5nCi9OYW1lIC9GMQovU3VidHlwZSAvVHlwZTEKL1R5cGUgL0ZvbnQKPj4KZW5kb2JqCjMgMCBvYmoKPDwKL0NvbnRlbnRzIDcgMCBSCi9NZWRpYUJveCBbIDAgMCA3MiA3MiBdCi9QYXJlbnQgNiAwIFIKL1Jlc291cmNlcyA8PAovRm9udCAxIDAgUgo+PgovUm90YXRlIDAKL1RyYW5zIDw8Cj4+Ci9UeXBlIC9QYWdlCj4+CmVuZG9iago0IDAgb2JqCjw8Ci9QYWdlTW9kZSAvVXNlTm9uZQovUGFnZXMgNiAwIFIKL1R5cGUgL0NhdGFsb2cKPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0F1dGhvciAoYW5vbnltb3VzKQovQ3JlYXRpb25EYXRlIChEOjIwMjYwMTI5MTgwOTQxKzAwJzAwJykKL0NyZWF0b3IgKFJlcG9ydExhYiBQREYgTGlicmFyeSAtIHd3dy5yZXBvcnRsYWIuY29tKQovS2V5d29yZHMgKCkKL01vZERhdGUgKEQ6MjAyNjAxMjkxODA5NDErMDAnMDAnKQovUHJvZHVjZXIgKFJlcG9ydExhYiBQREYgTGlicmFyeSAtIHd3dy5yZXBvcnRsYWIuY29tKQovU3ViamVjdCAoKQovVGl0bGUgKCkKL1RyYXBwZWQgL0ZhbHNlCj4+CmVuZG9iago2IDAgb2JqCjw8Ci9Db3VudCAxCi9LaWRzIFsgMyAwIFIgXQovVHlwZSAvUGFnZXMKPj4KZW5kb2JqCjcgMCBvYmoKPDwKL0xlbmd0aCAwCj4+CnN0cmVhbQplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA4CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDA5NSAwMDAwMCBuIAowMDAwMDAwMTI2IDAwMDAwIG4gCjAwMDAwMDAyNDEgMDAwMDAgbiAKMDAwMDAwMDQxMyAwMDAwMCBuIAowMDAwMDAwNDgzIDAwMDAwIG4gCjAwMDAwMDA3NzkgMDAwMDAgbiAKMDAwMDAwMDg1NiAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9JRCAKWyA8MjU2OTc0NjI5RkRBRjA1REY4RkY1Q0JBMkJEMzQyQkY+IDwyNTY5NzQ2MjlGREFGMDVERjhGRjVDQkEyQkQzNDJCRj4gXQovSW5mbyA1IDAgUgovUm9vdCA0IDAgUgovU2l6ZSA4Cj4+CnN0YXJ0eHJlZgoxMDAxCiUlRU9GCg==\"\n\n }","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/external-payments/:external_payment_id/receipt","description":"

This endpoint cancels a payment that has not yet been accepted by the recipient. It can be used to cancel payments that weren't accepted by the recipient yet.

The Payments section provides endpoints for managing individual and batch payments.

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":false},"event":[{"listen":"prerequest","script":{"id":"41a332f7-f907-4c0e-942f-27a1c346abeb","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"9253a74f-3916-45a2-af86-8595312ac1f4","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}],"_postman_id":"574be27a-e3bd-43f9-92d4-c9dd763696e6"},{"name":"Webhooks","item":[{"name":"Get Event Types","id":"87f283fa-b441-4698-94f8-b70abd0937a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/events","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}},"urlObject":{"protocol":"https","path":["events"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"7f543e7e-8528-405e-a8b4-618d8c21ea90","name":"Get Event Types","originalRequest":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/events"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"e32c6c36-c675-487a-971a-0530895d8688\",\n \"name\": \"payout.updated\",\n \"createdAt\": \"2026-03-03T19:25:08.725403+00:00\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"limit\": 100,\n \"offset\": 0\n }\n}"}],"_postman_id":"87f283fa-b441-4698-94f8-b70abd0937a3"},{"name":"Get Event Subscriptions","id":"af34b48f-5a6b-4671-8684-ffca577fe3c2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/events/subscription","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}},"urlObject":{"protocol":"https","path":["events","subscription"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"68179e2f-cd51-4549-9e50-61b4587e1dd7","name":"Get Event Subscriptions","originalRequest":{"method":"GET","header":[],"url":"https://payouts.api.trykarat.com/events/subscription"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"50fe99c8-6412-4557-91c8-c9d112dadbc7\",\n \"callbackUrl\": \"http://example.com/api/webhooks/callback\",\n \"createdAt\": \"2026-03-03T21:17:52.77594+00:00\",\n \"lastSentAt\": null,\n \"eventName\": \"payout.updated\"\n }\n ],\n \"meta\": {\n \"total\": 1,\n \"limit\": 100,\n \"offset\": 0\n }\n}"}],"_postman_id":"af34b48f-5a6b-4671-8684-ffca577fe3c2"},{"name":"Create Event Subscription","id":"4e02e1ee-950e-4319-9d44-818c8ad8d633","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\"event_name\": \"payout.updated\",\n\"callback_url\": \"http://localhost:3001/api/webhooks/callback/success\"\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/events/subscription","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}},"urlObject":{"protocol":"https","path":["events","subscription"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"4949b7d0-ae8e-44a1-b5b2-8806c02c6315","name":"Create Event Subscription","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"event_name\": \"payout.updated\",\n \"callback_url\": \"http://localhost:3001/api/webhooks/callback/success\"\n}","options":{"raw":{"language":"json"}}},"url":"https://payouts.api.trykarat.com/events/subscription"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"subscription\": {\n \"id\": \"50fe99c8-6412-4557-91c8-c9d112dadbc7\",\n \"eventName\": \"payout.updated\",\n \"callbackUrl\": \"http://example.com/api/webhooks/callback\",\n \"createdAt\": \"2026-03-03T21:17:52.77594+00:00\"\n },\n \"secret\": \"example_secret\"\n }\n}"}],"_postman_id":"4e02e1ee-950e-4319-9d44-818c8ad8d633"},{"name":"Delete Webhook Subscription","id":"8b350623-1264-4e9c-80c8-a7a93097e146","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"https://payouts.api.trykarat.com/events/subscription/ab707308-cbf1-4f54-94c6-84757bf90ce0","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}},"urlObject":{"protocol":"https","path":["events","subscription","ab707308-cbf1-4f54-94c6-84757bf90ce0"],"host":["payouts","api","trykarat","com"],"query":[],"variable":[]}},"response":[{"id":"ad3f25ae-0afb-4c0c-a4e2-2be97c6e0b6f","name":"Delete Webhook Subscription","originalRequest":{"method":"DELETE","header":[],"url":"https://payouts.api.trykarat.com/events/subscription/50fe99c8-6412-4557-91c8-c9d112dadbc7"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"50fe99c8-6412-4557-91c8-c9d112dadbc7\",\n \"success\": true,\n \"deletedAt\": \"2026-03-03T22:10:37.398+00:00\"\n }\n}"}],"_postman_id":"8b350623-1264-4e9c-80c8-a7a93097e146"}],"id":"9ac514bf-4127-41e7-be22-e8dcc6f6b580","description":"

Webhooks allow you to receive real-time notifications when events occur in the Payouts API. You register a callback URL for a specific event type; when that event fires, a POST request is sent to your URL with the event payload.

Available Events

payout.updated

{\n   \"id\":\"a2b6f9c8-7d5f-4c2b-bd7a-1c2f9b5c44b9\",\n   \"event\":\"payout.updated\",\n   \"created_at\":\"2026-03-02T12:34:56Z\",\n   \"subscription_id\":\"7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d\",\n   \"data\":{\n      \"id\": \"8e0c87c1-948c-4e57-9b48-9b5ab4c0d7e8\",\n      \"status\":\"created\",\n      \"reason\":null,\n      \"reference_id\": \"6ae5b965-ad32-4d21-bff9-f1e661f05ca3\",\n      \"payout_intent_id\":\"05545ccf-0798-4661-8b36-2ad7c0bf5375\",\n      \"date\":\"2025-09-30T14:59:37.055Z\"\n   }\n}\n\n

tax_form.created

{\n  \"id\": \"78ce3584-0761-40ab-bcb1-ef7c5bffe095\",\n  \"event\": \"tax_form.created\",\n  \"created_at\": \"2026-03-10T23:45:07.878Z\",\n  \"subscription_id\": \"48582de1-c2fb-4fd3-bdf3-39a7138d1164\",\n  \"data\": {\n    \"id\": \"ffc96bee-3ce9-4bfc-a436-c08cc2a3d33e\",\n    \"recipient\": {\n      \"id\": \"db783652-823b-46f8-88e2-93ae37442232\",\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"nickname\": null\n    },\n    \"createdAt\": \"2026-03-10T23:45:07.868Z\",\n    \"url\": \"https://url.com/pdf\"\n  }\n}\n\n

Possible Statuses for payout.updated

created - payout is initiated
\n
awaiting_acceptance - payee pending acceptance
\n
pending - payout's being processed
\n
completed - payout is settled
\n
canceled - payer canceled the payout
\n
failed - payout failed
\n
returned - payout was returned
\n

Webhook delivery authentication

Karat signs every webhook request. Use the subscription secret to verify authenticity and
integrity.

Secret generation

Karat generates a unique signing secret when you create a subscription.
The secret is returned only once in the create subscription response.

Handshake verification

When creating a subscription, the API verifies ownership of the callback URL by performing
a challenge-response handshake. Your server must handle this before the subscription is
accepted.

How it works:

The API sends a POST request to your callback_url with a JSON body:

{\n   \"type\":\"url_verification\",\n   \"challenge\":\"a3f8b2e...\"\n}\n\n

Your server must respond within 30 seconds with:

HTTP status 200
A JSON body echoing the challenge:

{\n   \"challenge\":\"a3f8b2e...\"\n}\n\n

If verification succeeds, the subscription is created. If it fails, the API returns a 400 error with one of these messages:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Message	Cause
Callback URL verification failed: could not reach the URL	The URL was unreachable, timed out, or the connection was refused
Callback URL verification failed: received status {code}	Your server responded with a non-2xx status code
Callback URL verification failed: invalid JSON response	The response body was not valid JSON
Callback URL verification failed: challenge mismatch	The `challenge` value in the response did not match the one sent

Headers sent on every delivery

X-Karat-Webhook-Id
Unique id for the delivery attempt. Use for idempotency and deduplication.
\n
X-Karat-Webhook-Timestamp
Unix epoch seconds. Used for replay protection.
\n
X-Karat-Subscription-Id
Subscription id used to look up the signing secret.
\n
X-Karat-Signature
Signature header in the format v1=.
\n

Signature computation

Inputs:

secret is your stored signing secret for the subscription
\n
timestamp is X-Karat-Webhook-Timestamp
\n
raw_body is the exact raw request body bytes
\n

Signed payload:

signed_payload = timestamp + \".\" + raw_body

Compute the HMAC SHA256 and encode in base64:

signature_bytes = HMAC_SHA256(secret, signed_payload)
\n
signature_base64 = BASE64(signature_bytes)
\n

Sender includes:

X-Karat-Signature: v1=

Receiver verification steps

Read X-Karat-Subscription-Id and look up the correct secret.
\n
Validate timestamp freshness. Recommended window is plus or minus 300 seconds.
\n
Read the raw request body bytes exactly as received.
\n
Recompute the signature using the same method.
\n
Compare signatures using a constant time comparison.
\n
If valid, parse JSON and process.
\n
Deduplicate using X-Karat-Webhook-Id and the JSON body field id.
\n

Recommended consistency check after signature verification: confirm the JSON body field subscription_id equals the header X-Karat-Subscription-Id.

Responses and retries

Return any 2xx response code to acknowledge success.
\n
Non 2xx responses or timeouts will be retried with exponential backoff for up to 3 days.
\n
Avoid redirects.
\n

Idempotency

Because webhooks can be delivered more than once, implement idempotency. Store processed ids for a reasonable retention window and ignore duplicates.

Secret rotation

If you need to rotate a secret:

Create a new subscription and store the new secret.
\n
Deploy your receiver to use the new subscription secret.
\n
Delete the old subscription.
\n

Best practices

Use HTTPS in production.
\n
Respond quickly and do heavy work asynchronously.
\n
Do not log secrets.
\n
Ensure your framework provides access to the raw request body.
\n

\n","_postman_id":"9ac514bf-4127-41e7-be22-e8dcc6f6b580","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]},"isInherited":true,"source":{"_postman_id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","id":"c9de821b-0b9b-40ae-b8a0-a311b49d417a","name":"Karat Payout API","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{api_key}}"}]}},"event":[{"listen":"prerequest","script":{"id":"9cb16db1-d16b-4ff7-a60b-873c9a4171fe","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"855fd745-91d1-4372-b367-9b2f8655c963","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}]}