---
title: "Create Payout"
method: POST
path: "/v1/payment/payouts"
tags: ["Payout Services"]
---

# Create Payout

`POST /v1/payment/payouts`

In the payout service creation, all the required fields will be validated at first, after that, business validation rules will be run. The next table shows the information about the API.

## Headers

- `Content-Type` string, required
- `Accept` string, required

## Request body

- union
  - Payout
    - `store` object, required
      - `code` string, required
    - `transaction` PayoutTransaction, required
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payment. (Maximum of 50 characters - Unique per transaction)
      - `account` string, required — Client account number provided by Koin.
      - `amount` object, required
        - `currency_code` string, required — Payout currency code (ISO 4217)
        - `value` number, required — Payout total amount.
    - `payment_method` PayoutPaymentMethod, required
      - `code` string, required — Payment method code
      - `recipient` object, required
        - `id` string — Identifier search recipient.
        - `payment_key` string — Receiver pix key. Options are CNPJ, CPF, telephone, email, or random payment key (max 100 characters).
        - `full_name` string — Full name. If the length of the field exceeds 100 characters it will be truncated.
        - `document` object
          - `type` 'cpf' | 'cnpj', required — Receiver document type (cpf, cnpj).
          - `number` string, required — Receiver document number.
        - `account` object
          - `ispb` string — Brazilian Payment System Identifier (eight-number length).
          - `agency` string — Receiver account Agency.
          - `code` string — Receiver account number.
          - `type` 'CA' | 'CC' | 'CS' — Receiver account type.
    - `notification_url` string[], required — List of URLs to which notifications will be sent
    - `descriptor` string — Text send to client. Maximum of 140 characters.
  - PayoutCrypto
    - `store` object, required
      - `code` string, required
    - `transaction` PayoutTransactionCrypto, required
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payout. (Maximum of 50 characters - Unique per transaction)
      - `account` string, required — Client account number provided by Koin.
      - `amount` object, required
        - `currency` string, required — Payout currency code (ISO 4217)
        - `value` number, required — Payout total amount.
    - `method` PayoutMethodCrypto, required
      - `code` string, required — Crypto Payout method code
      - `quotation_id` string, required — Value returned by the quote service. (quotation.id)
    - `notification_url` string[], required — List of URLs to which notifications will be sent
    - `descriptor` string — Text send to client. Maximum of 140 characters.
    - `payer` object, required
      - `email` string, required — Payer email

## Response `200`

Create payout response

- union
  - PayoutResponse
    - `status` object
      - `type` 'Opened' | 'Transferred' | 'Failed', required — Payout status.
      - `reason` 'Rejected' | 'ConnectionRefused' — Reason status.
      - `message` string — Message associated with the reason
      - `date` string, date-time, required — Status change date (ISO 8601 date format)
      - `error` StatusError — Error details. Present when the payment failed and error information is available.
        - `code` string — Error code.
        - `message` string — Error message.
    - `store` object
      - `code` string
    - `descriptor` string — Text send to client. Maximum of 140 characters.
    - `transaction` PayoutTransactionCrypto
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payout. (Maximum of 50 characters - Unique per transaction)
      - `account` string, required — Client account number provided by Koin.
      - `amount` object, required
        - `currency` string, required — Payout currency code (ISO 4217)
        - `value` number, required — Payout total amount.
    - `payment_method` PayoutPaymentMethod
      - `code` string, required — Payment method code
      - `recipient` object, required
        - `id` string — Identifier search recipient.
        - `payment_key` string — Receiver pix key. Options are CNPJ, CPF, telephone, email, or random payment key (max 100 characters).
        - `full_name` string — Full name. If the length of the field exceeds 100 characters it will be truncated.
        - `document` object
          - `type` 'cpf' | 'cnpj', required — Receiver document type (cpf, cnpj).
          - `number` string, required — Receiver document number.
        - `account` object
          - `ispb` string — Brazilian Payment System Identifier (eight-number length).
          - `agency` string — Receiver account Agency.
          - `code` string — Receiver account number.
          - `type` 'CA' | 'CC' | 'CS' — Receiver account type.
    - `payout_id` string — Payout Id returned by Create Payout API.
    - `code` string — Standardized error code (applies only for error cases)
    - `message` string — Message associated with the error code (applies only for error cases)
  - CryptoPayoutResponse
    - `status` object
      - `type` 'Opened' | 'Transferred' | 'Failed', required — Payout status.
      - `date` string, date-time, required — Status change date (ISO 8601 date format)
      - `error` StatusError — Error details. Present when the payment failed and error information is available.
        - `code` string — Error code.
        - `message` string — Error message.
    - `store` object
      - `code` string — Store identifier.
    - `descriptor` string — Text send to client. Maximum of 140 characters.
    - `transaction` PayoutTransaction
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payment. (Maximum of 50 characters - Unique per transaction)
      - `account` string, required — Client account number provided by Koin.
      - `amount` object, required
        - `currency_code` string, required — Payout currency code (ISO 4217)
        - `value` number, required — Payout total amount.
    - `method` PayoutMethodCrypto
      - `code` string, required — Crypto Payout method code
      - `quotation_id` string, required — Value returned by the quote service. (quotation.id)
    - `payout_id` string — Payout Id returned by Create Payout API.
    - `code` string — Standardized error code (applies only for error cases)
    - `message` string — Message associated with the error code (applies only for error cases)

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/koin/apis/payments-api.md) · [All operations](https://skmtc.dev/koin/apis/payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/koin/payments-api/revisions/6f2c01e43fe2/schema)