# Create a payout request

Creates a payout request.
In the response, the `selectPaymentInstrumentUrl` field is used to redirect the customer to select a preferred payment instrument.
After a payment instrument is selected, the customer is redirected to the `selectedPaymentInstrumentRedirectUrl` value.
> **Important:** The selected payment gateway must be configured to support payout requests.
For more information, see the [readyToPayoutInstruction](https://www.rebilly.com/catalog/all/gateway-accounts/getgatewayaccountcollection#gateway-accounts/getgatewayaccountcollection/t=response&c=200&path=&d=0/readytopayoutinstruction) field.

Endpoint: POST /payout-requests
Version: latest
Security: SecretApiKey, JWT

## Security:

  - `SecretApiKey` (unknown)
    apiKey in header REB-APIKEY

  - `JWT` (unknown)
    http bearer JWT

## Request body:

  - `application/json` (unknown)
    Payout request resource.

## Request fields (application/json):

  - `websiteId` (string, required)
    ID of the website.
A website is where an organization obtains a customer.
For more information, see [Obtain an organization ID and website ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
    Example: web_0YV7DE4Z26DQSA1AC92FBJ7SEG

  - `customerId` (string, required)
    ID of the customer resource.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

  - `paymentInstrumentId` (string | null)
    ID of the requested payment instrument to offer for the payout.
    Example: inst_0YVB8KPKNXCBR9EDX7JHSED75N

  - `currency` (string, required)
    Currency code in ISO 4217 format.
    Example: USD

  - `amount` (number, required)
    Amount of the payout.

  - `description` (string | null)
    Description of payout request.

  - `blocked` (boolean)
    Specifies whether the payout request is blocked or unblocked.
When blocked, the payout request cannot transition to `ready`, `approved`, `in-progress`, `merged`, `split`, or `canceled`.
Allocation creation, allocation processing, and cancellation of pending allocations are also prevented.
A blocked payout request can still transition to the `fulfilled` status if allocation processing starts before the payout request is blocked.
    Example: false

  - `blockReason` (any)

  - `splitReason` (any)

  - `selectedPaymentInstrumentRedirectUrl` (string)
    URL where the customer is redirected when a payment instrument is selected. The default value is the website URL.
Use `{{id}}` as a placeholder for the payout request ID.
    Example: https://example.com/payout-request-success

## Response 201:

  - `201` (unknown)
    Payout request created.

## Response 201 fields (application/json):

  - `id` (string)
    Unique resource ID.
    Example: pout_req_0YVDMDE2BMC6KBB5MX76RF6T80

  - `websiteId` (string, required)
    ID of the website.
A website is where an organization obtains a customer.
For more information, see [Obtain an organization ID and website ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
    Example: web_0YV7DE4Z26DQSA1AC92FBJ7SEG

  - `customerId` (string, required)
    ID of the customer resource.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

  - `paymentInstrumentId` (string | null)
    ID of the requested payment instrument to offer for the payout.
    Example: inst_0YVB8KPKNXCBR9EDX7JHSED75N

  - `splitFromPayoutRequestId` (string | null)
    ID of the payout request from which this request is split,
or `null` if this request is not created by a split operation.
    Example: pout_req_0YVDMDE2BMC6KBB5MX76RF6T80

  - `mergedIntoPayoutRequestId` (string | null)
    ID of the payout request that this request is merged into,
or `null` if it is not merged into another request.
    Example: pout_req_0YVDMDE2BMC6KBB5MX76RF6T80

  - `currency` (string, required)
    Currency code in ISO 4217 format.
    Example: USD

  - `amount` (number, required)
    Amount of the payout.

  - `availableAmount` (number)
    Available payout request amount that has not been allocated.

  - `description` (string | null)
    Description of payout request.

  - `status` (string)
    Status of the request.
    Enum: "pending", "ready", "approved", "in-progress", "fulfilled", "canceled", "split", "merged"

  - `blocked` (boolean)
    Specifies whether the payout request is blocked or unblocked.
When blocked, the payout request cannot transition to `ready`, `approved`, `in-progress`, `merged`, `split`, or `canceled`.
Allocation creation, allocation processing, and cancellation of pending allocations are also prevented.
A blocked payout request can still transition to the `fulfilled` status if allocation processing starts before the payout request is blocked.
    Example: false

  - `blockReason` (any)

  - `splitReason` (any)

  - `batchId` (string | null)
    ID of the payout request batch that contains this request.
    Example: prb_0YVDMDE2BMC6KBB5MX76RF6T80

  - `selectPaymentInstrumentUrl` (string)
    URL for the customer to select a preferred payment instrument.

  - `allocations` (array)
    List of payout request allocations for the payout request.

  - `allocations.id` (string)
    ID of the resource.
    Example: pra_0YVDMDE2BMC6KBB5MX76RF6T80

  - `allocations.payoutRequestId` (string, required)
    ID of the payout request associated with this allocation.
    Example: pout_req_0YVDMDE2BMC6KBB5MX76RF6T80

  - `allocations.batchId` (string | null)
    ID of the payout request batch that contains the payout request for this allocation.
    Example: prb_0YVDMDE2BMC6KBB5MX76RF6T80

  - `allocations.paymentInstrumentId` (string, required)
    ID of the payment instrument allocated to the payout request.
    Example: inst_0YVB8KPKNXCBR9EDX7JHSED75N

  - `allocations.paymentMethod` (string)
    Payment method of the allocation.
    Enum: "payment-card", "ach", "cash", "check", "paypal", "AdvCash", "Aera", "Affirm", "Afterpay", "Aircash", "Airpay", "Alfa-click", "Alipay", "AmazonPay", "Apple Pay", "AstroPay Card", "AstroPay-GO", "BankSEND", "BankReferenced", "bank-transfer", "bank-transfer-2", "bank-transfer-3", "bank-transfer-4", "bank-transfer-5", "bank-transfer-6", "bank-transfer-7", "bank-transfer-8", "bank-transfer-9", "Baloto", "Beeline", "Belfius-direct-net", "bitcoin", "Bizum", "Blik", "Boleto", "Boleto-2", "Boleto-3", "cash-deposit", "CASHlib", "CashToCode", "CCAvenue", "China UnionPay", "Clearpay", "Cleo", "CODVoucher", "Conekta-oxxo", "Conekta-spei", "cryptocurrency", "Cupon-de-pagos", "CyberSource", "Dimoco-pay-smart", "Directa24Card", "domestic-cards", "Efecty", "echeck", "ecoPayz", "ecoPayzTurkey", "ecoVoucher", "EPS", "ePay.bg", "Ethereum", "e-wallet", "ezyEFT", "eZeeWallet", "FasterPay", "Flexepin", "Giropay", "Google Pay", "Gpaysafe", "iCashOne Voucher", "iDebit", "iDEAL", "ING-homepay", "INOVAPAY-pin", "INOVAPAY-wallet", "InstaDebit", "InstantPayments", "instant-bank-transfer", "Interac-online", "Interac-eTransfer", "Interac-express-connect", "Interac", "invoice", "iWallet", "Jeton", "JetonCash", "jpay", "KakaoPay", "Khelocard", "Klarna", "KNOT", "Litecoin", "loonie", "LPG-online", "LPG-payment-card", "Matrix", "MaxiCash", "Megafon", "MercadoPago", "MiFinity-eWallet", "miscellaneous", "MobilePay", "Mollie", "Multibanco", "Bancontact", "Bancontact-mobile", "MTS", "MuchBetter", "MuchBetterVoucher", "MyFatoorah", "Neosurf", "Netbanking", "Neteller", "Nordea-Solo", "NordikCoin", "OchaPay", "online-bank-transfer", "Onlineueberweisen", "oriental-wallet", "OXXO", "P24", "Pagadito", "PagoEffectivo", "Pagsmile-lottery", "Pagsmile-deposit-express", "PayCash", "Payco", "Payeer", "PaymentAsia-crypto", "Paysafecard", "PayTabs", "Pay4Fun", "Paynote", "Paymero", "Paymero-QR", "PayU", "PayULatam", "Perfect-money", "Piastrix", "PIX", "PIX-Automatico", "PinPay", "phone", "PhonePe", "POLi", "PostFinance-card", "PostFinance-e-finance", "QIWI", "QPay", "QQPay", "Quickpay", "rapyd-checkout", "rebilly-hosted-payment-form", "Resurs", "reverse-withdrawal", "Ripple", "SafetyPay", "Samsung Pay", "SEPA", "Siirto", "Skrill", "Skrill Rapid Transfer", "SMSVoucher", "Sofort", "SparkPay", "SPEI", "swift-dbt", "Tele2", "Telr", "Terminaly-RF", "Tether", "ToditoCash-card", "Trustly", "Tupay", "TWINT", "UniCrypt", "UPayCard", "UPI", "USD-coin", "VCreditos", "VegaWallet", "VenusPoint", "Viva", "voucher", "voucher-2", "voucher-3", "voucher-4", "Wallet88", "Webmoney", "Webpay", "Webpay-2", "Webpay Card", "WeChat Pay", "XPay-P2P", "XPay-QR", "Yandex-money", "Zotapay", "Zimpler", "Zip"

  - `allocations.gatewayAccountId` (string, required)
    ID of the gateway account to use for processing this allocation.
    Example: gateway_0YVB8KPKNXCBR9EDX7JHSED75N

  - `allocations.gatewayName` (string)
    Name of the gateway account to use for processing this allocation.
    Example: TestProcessor

  - `allocations.gatewayPayoutInstruction` (string | null)
    Payout configuration of the gateway account that processes this allocation.
    Enum: "all", "covered-payout", "approved-payment", "none", null

  - `allocations.amount` (number, required)
    Amount allocated to this payment instrument.

  - `allocations.exposureAmount` (number)
    Approved sales and captures minus approved payouts for the customer,
gateway account, and payment instrument, in the allocation currency.
The calculation includes only transactions created within the last 180 days.
The value is `0` when there are no transactions in the last 180 days,
the gateway account is inactive,
or its `readyToPayoutInstruction` is `none`.
    Example: 2

  - `allocations.status` (string)
    Status of this payout request allocation.
    Enum: "pending", "queued", "processing", "waiting-completion", "completed", "failed", "canceled", "declined"

  - `allocations.transactionId` (string | null)
    ID of the transaction that is created when processing this allocation, if applicable.
    Example: txn_0YVB8KPKNXCBR9EDX7JHSED75N

  - `allocations.transactionResult` (string | null)
    Result of the transaction created for this allocation, if applicable.
    Enum: "abandoned", "approved", "canceled", "declined", "unknown", null

  - `allocations.transactionStatus` (string | null)
    Status of the transaction created for this allocation, if applicable.
    Enum: "completed", "conn-error", "disputed", "never-sent", "offsite", "partially-refunded", "pending", "refunded", "sending", "timeout", "voided", "waiting-approval", "waiting-capture", "waiting-gateway", "waiting-refund", null

  - `allocations.createdTime` (string)
    Date and time when the resource is created.
This value is set automatically when the resource is created.

  - `allocations.updatedTime` (string)
    Date and time when the resource is updated.
This value is set automatically when the resource is updated.

  - `allocations._links` (array)
    Related links.

  - `allocations._links.href` (string)
    Link URL.

  - `allocations._links.rel` (string)
    Type of link.
    Enum: "self", "transaction", "gatewayAccount", "payoutRequest", "paymentInstrument"

  - `selectedPaymentInstrumentRedirectUrl` (string)
    URL where the customer is redirected when a payment instrument is selected. The default value is the website URL.
Use `{{id}}` as a placeholder for the payout request ID.
    Example: https://example.com/payout-request-success

  - `cancellationReason` (object | null)
    Reason the payout request is canceled.

  - `cancellationReason.canceledBy` (string)
    Specifies who initiated the cancellation.
    Enum: "merchant", "customer", "system"

  - `cancellationReason.description` (string)
    Description of the cancellation reason in free form.

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
    Enum: "self", "splitFrom", "mergedInto", "paymentInstrument"

## Response 201 headers (application/json):

  - `Location` (string)
    Location of the related resource.
    Example: https://api.rebilly.com/example

  - `X-RateLimit-Limit` (integer)
    Total number of rate limit tokens for this request within a rate limit period.
For more information, see [Rate limits](#section/Rate-limits).
    Example: 3600

  - `X-RateLimit-Remaining` (integer)
    Remaining number of rate limit tokens for this request within the rate limit period. 
For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.
    Example: 3600

## Response 401:

  - `401` (unknown)
    Unauthorized access.
Invalid credentials used.

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403:

  - `403` (unknown)
    Access forbidden.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 422:

  - `422` (unknown)
    Invalid data sent.

## Response 422 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

  - `invalidFields` (array)
    Invalid field details.
    Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]

  - `invalidFields.field` (string)
    Name of the field.
Dot notation is used for nested object field names.

  - `invalidFields.message` (string)
    Message field.

## Response 429:

  - `429` (unknown)
    Request rate limit exceeded.

## Response 429 fields (application/json):

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".
    Example: about:blank

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
    Example: Rate Limit Exceeded

  - `status` (integer)
    HTTP status code.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.
    Example: A request cannot be executed because the user has sent too many requests within a certain period of time

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 429 headers (application/json):

  - `X-RateLimit-Retry-After` (integer)
    UTC timestamp after which the rate limit resets and the request can be retried.
    Example: 1713187500