Create Payout Request

Create payout request

Allows a merchant to invite clients to sign up for a BitPay personal account.

POST /payouts

Facades PAYOUT

HTTP Request

An example code of the create payout request

var ledgerCurrency = Currency.ETH;
var currency = Currency.USD;
var payout = new Payout(5.0, currency, ledgerCurrency);
var recipients = bitpay.GetPayoutRecipients("active", 1);
payout.RecipientId = recipients.First().Id;
payout.NotificationUrl = "https://hookbin.com/yDEDeWJKyasG9yjj9X9P";
var createPayout = bitpay.SubmitPayout(payout);

The BitPay server shall return an HTTP 200 OK response, and the body of the response shall be the payout object.

The following table gives a description of the Payout object and all the fields returned by the BitPay server when merchants create or retrieve a payout request. The following subsections will use this table as a reference for the body of the server response.

Name	Description	Type
facade	This indicates the facade used to create the payout request. When the payout facade is used to create a payout request, the BitPay server returns the payout object as seen from the payout facade, that is `"payout/payout"`.	`string`
data	Payout data object.	`object`
→ id	Payout request id.	`string`
→ recipientId	BitPay recipient id, assigned by BitPay for a given recipient email during the onboarding process (see Recipients resource).	`string`
→ shopperId	This is the unique id assigned by BitPay if the shopper used his personal BitPay account to authenticate and pay an invoice. For customers signing up for a brand new BitPay personal account, this id will only be created as part of the payout onboarding. The same field would also be available on paid invoices for customers who signed in with their BitPay personal accounts before completing the payment. This can allow merchants to monitor the activity of a customer (deposits & payouts).	`string`
→ amount	The amount to be sent to the recipient in the indicated `currency`. The minimum amount per instruction is `$5 USD` equivalent.	`number`
→ currency	Currency code set for the batch amount (ISO 4217 3-character currency code).	`string`
→ ledgerCurrency	Ledger currency code set for the payout request (ISO 4217 3-character currency code), it indicates on which ledger the payout request will be recorded. If not provided in the request, this parameter will be set by default to the active ledger currency on your account, e.g. your settlement currency. Supported ledger currency codes for payout requests are EUR, USD, GBP, CAD, NZD, AUD, ZAR, JPY, BTC, BCH, GUSD, USDC, PAX, XRP, BUSD, DOGE, ETH, WBTC, DAI.	`string`
→ exchangeRates	Exchange rates keyed by source and target currencies.	`array`
→ email	Email address of an active recipient. Note: In the future, BitPay may allow recipients to update the email address tied to their personal account. BitPay encourages the use of `recipientId` or `shopperId` when programatically creating payouts requests.	`string`
→ reference	Present only if specified by the merchant in the request. Merchants can pass their own unique identifier in this field for reconciliation purposes. Maximum string length is 100 characters.	`string`
→ label	For merchant use, pass through - can be the customer name or unique merchant reference assigned by the merchant to the recipient.	`string`
→ notificationURL	URL to which BitPay sends webhook notifications. HTTPS is mandatory	`string`
→ notificationEmail	Merchant email address for notification of payout status change.	`string`
→ effectiveDate	DescrEffective date and time (UTC) for the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ` - Note that the time of day will automatically be set to 09:00:00.000 UTC time for the given day.iption	`string`
→ requestDate	Date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.	`string`
→ status	Payout request status, the possible values are: ● new - initial status when the payout batch is created ● funded - if there are enough funds available on the merchant account, the payout batches are set to funded. This happens at the daily cutoff time for payout processing, e.g. 2pm and 9pm UTC ● processing - the payout batches switch to this status whenever the corresponding cryptocurrency transactions are broadcasted by BitPay ● complete - the payout batches are marked as complete when the cryptocurrency transaction has reached the typical target confirmation for the corresponding asset. For instance, 6 confirmations for a bitcoin transaction. ● cancelled - when the merchant cancels a payout batch (only possible for requests in the status new	`string`
→ transactions	Contains the cryptocurrency transaction details for the executed payout request.	`string`
→ → txid	Cryptocurrency transaction hash for the executed payout.	`string`
→ → amount	Amount of cryptocurrency sent to the requested address.	`number`
→ → date	Date and time (UTC) when the cryptocurrency transaction is broadcasted. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.	`string`
→ token	Resource token - this token is actually derived from the API token used to submit the payout request and is tied to the specific payout resource id created.	`string`
status	Set to `success` in case of successful request and to `error` if the request failed, a description of the error will then be indicated in the `message` field.	`string`
message	In case of error, this field will contain a description message. Set to `null` if the request is successful.	`string`

HTTP Response

{
    "facade":"payout/payout",
    "data":{
        "id":"JMwv8wQCXANoU2ZZQ9a9GH",
        "recipientId":"LDxRZCGq174SF8AnQpdBPB",
        "shopperId":"7qohDf2zZnQK5Qanj8oyC2",
        "amount":10,
        "currency":"USD",
        "ledgerCurrency":"GBP",
        "exchangeRates":{
            "BTC":{
                "USD":39390.47,
                "GBP":27883.962246420004
            }
        },
        "email":"[email protected]",
        "reference":"payout_20210527",
        "label":"John Doe",
        "notificationURL":"https://yournotiticationURL.com/wed3sa0wx1rz5bg0bv97851eqx",
        "notificationEmail":"[email protected]",
        "effectiveDate":"2021-05-27T09:00:00.000Z",
        "requestDate":"2021-05-27T10:47:37.834Z",
        "status":"complete",
        "transactions":[
            {
                "txid":"db53d7e2bf3385a31257ce09396202d9c2823370a5ca186db315c45e24594057",
                "amount":0.000254,
                "date":"2021-05-27T11:04:23.155Z"
            }
        ],
        "token":"6RZSTPtnzEaroAe2X4YijenRiqteRDNvzbT8NjtcHjUVd9FUFwa7dsX8RFgRDDC5SL"
    },
    "status":"success",
    "message":null
}