BitPay PHP SDK

Payout
in package

Tags
author

BitPay Integrations integrations@bitpay.com

license

http://www.opensource.org/licenses/mit-license.php MIT

see
https://bitpay.readme.io/reference/payouts

REST API Payouts

Table of Contents

Properties

$accountId  : string|null
$amount  : float|null
$code  : int|null
$currency  : string|null
$dateExecuted  : string|null
$effectiveDate  : string|null
$email  : string|null
$exchangeRates  : array<string|int, mixed>|null
$groupId  : string|null
$id  : string|null
$ignoreEmails  : bool
$label  : string|null
$ledgerCurrency  : string|null
$message  : string|null
$notificationEmail  : string|null
$notificationURL  : string|null
$recipientId  : string|null
$reference  : string|null
$requestDate  : string|null
$shopperId  : string|null
$status  : string|null
$token  : string|null
$transactions  : array<string|int, PayoutTransaction>

Methods

__construct()  : mixed
Constructor, create a request Payout object.
formatAmount()  : void
Change amount value based on precision rounding.
getAccountId()  : string
Gets BitPay account id that is associated to the payout, assigned by BitPay for a given account during the onboarding process.
getAmount()  : float|null
Gets amount of cryptocurrency sent to the requested address.
getCode()  : int|null
This field will be returned in case of error and contain an error code.
getCurrency()  : string|null
Gets currency code set for the batch amount (ISO 4217 3-character currency code).
getDateExecuted()  : string|null
Gets date and time (UTC) when BitPay executed the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
getEffectiveDate()  : string|null
Gets Ledger currency code (ISO 4217 3-character currency code)
getEmail()  : string
Gets email.
getExchangeRates()  : array<string|int, mixed>|null
Gets exchange rates keyed by source and target currencies.
getGroupId()  : string|null
Gets group id.
getId()  : string|null
Gets Payout request id.
getLabel()  : string
Gets label.
getLedgerCurrency()  : string|null
Gets Ledger currency code (ISO 4217 3-character currency code
getMessage()  : string
Gets message.
getNotificationEmail()  : string
Gets notification email.
getNotificationURL()  : string
Gets notification url.
getRecipientId()  : string
Gets BitPay recipient id. Assigned by BitPay for a given recipient email during the onboarding process.
getReference()  : string
Gets reference.
getRequestDate()  : string|null
Gets date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.
getShopperId()  : string
Gets shopper id.
getStatus()  : string|null
Gets payout request status.
getToken()  : string
Gets resource token.
getTransactions()  : array<string|int, PayoutTransaction>
Gets transactions. Contains the cryptocurrency transaction details for the executed payout request.
isIgnoreEmails()  : bool
Gets boolean to prevent email updates on a specific payout.
setAccountId()  : void
Sets BitPay account id that is associated to the payout, assigned by BitPay for a given account during the onboarding process.
setAmount()  : void
Sets amount of cryptocurrency sent to the requested address.
setCode()  : void
Sets error code.
setCurrency()  : void
Sets currency code set for the batch amount (ISO 4217 3-character currency code).
setDateExecuted()  : void
Sets date and time (UTC) when BitPay executed the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
setEffectiveDate()  : void
Sets effective date and time (UTC) for the payout.
setEmail()  : void
Sets email.
setExchangeRates()  : void
Sets exchange rates keyed by source and target currencies.
setGroupId()  : void
Sets group id.
setId()  : void
Sets Payout request id.
setIgnoreEmails()  : void
Sets boolean to prevent email updates on a specific payout.
setLabel()  : void
Sets label.
setLedgerCurrency()  : void
Sets Ledger currency code (ISO 4217 3-character currency code)
setMessage()  : void
Sets message.
setNotificationEmail()  : void
Sets notification email.
setNotificationURL()  : void
Sets notification url.
setRecipientId()  : void
Sets BitPay recipient id. Assigned by BitPay for a given recipient email during the onboarding process.
setReference()  : void
Sets reference.
setRequestDate()  : void
Sets date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.
setShopperId()  : void
Sets shopper id.
setStatus()  : void
Sets payout request status.
setToken()  : void
Sets resource token.
setTransactions()  : void
Sets transactions. Contains the cryptocurrency transaction details for the executed payout request.
toArray()  : array<string|int, mixed>
Return Payout values as array.

Properties

$accountId

protected string|null $accountId = null

$amount

protected float|null $amount = null

$code

protected int|null $code = null

$currency

protected string|null $currency = null

$dateExecuted

protected string|null $dateExecuted = null

$effectiveDate

protected string|null $effectiveDate = null

$email

protected string|null $email = null

$exchangeRates

protected array<string|int, mixed>|null $exchangeRates = null

$groupId

protected string|null $groupId = null

$id

protected string|null $id = null

$ignoreEmails

protected bool $ignoreEmails = false

$label

protected string|null $label = null

$ledgerCurrency

protected string|null $ledgerCurrency = null

$message

protected string|null $message = null

$notificationEmail

protected string|null $notificationEmail = null

$notificationURL

protected string|null $notificationURL = null

$recipientId

protected string|null $recipientId = null

$reference

protected string|null $reference = null

$requestDate

protected string|null $requestDate = null

$shopperId

protected string|null $shopperId = null

$status

protected string|null $status = null

$token

protected string|null $token = null

Methods

__construct()

Constructor, create a request Payout object.

public __construct([float|null $amount = null ][, string|null $currency = null ][, string|null $ledgerCurrency = null ]) : mixed
Parameters
$amount : float|null = null

float The amount for which the payout will be created.

$currency : string|null = null

string The three digit currency string for the PayoutBatch to use.

$ledgerCurrency : string|null = null

string 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.

formatAmount()

Change amount value based on precision rounding.

public formatAmount(int $precision) : void
Parameters
$precision : int

getAccountId()

Gets BitPay account id that is associated to the payout, assigned by BitPay for a given account during the onboarding process.

public getAccountId() : string
Return values
string

getAmount()

Gets amount of cryptocurrency sent to the requested address.

public getAmount() : float|null
Return values
float|null

getCode()

This field will be returned in case of error and contain an error code.

public getCode() : int|null
Return values
int|null

getCurrency()

Gets currency code set for the batch amount (ISO 4217 3-character currency code).

public getCurrency() : string|null
Return values
string|null

getDateExecuted()

Gets date and time (UTC) when BitPay executed the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.

public getDateExecuted() : string|null
Return values
string|null

getEffectiveDate()

Gets Ledger currency code (ISO 4217 3-character currency code)

public getEffectiveDate() : string|null

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.

Tags
see
https://bitpay.com/api/#rest-api-resources-payouts

Supported ledger currency codes

Return values
string|null

getEmail()

Gets email.

public getEmail() : string

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.

Return values
string

getExchangeRates()

Gets exchange rates keyed by source and target currencies.

public getExchangeRates() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null

getGroupId()

Gets group id.

public getGroupId() : string|null
Return values
string|null

getId()

Gets Payout request id.

public getId() : string|null
Return values
string|null

getLabel()

Gets label.

public getLabel() : string

For merchant use, pass through - can be the customer name or unique merchant reference assigned by the merchant to the recipient.

Return values
string

getLedgerCurrency()

Gets Ledger currency code (ISO 4217 3-character currency code

public getLedgerCurrency() : string|null

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.

Tags
see
https://bitpay.com/api/#rest-api-resources-payouts

Supported ledger currency codes

Return values
string|null

getMessage()

Gets message.

public getMessage() : string

In case of error, this field will contain a description message. Set to null if the request is successful.

Return values
string

getNotificationEmail()

Gets notification email.

public getNotificationEmail() : string

Merchant email address for notification of payout status change.

Return values
string

getNotificationURL()

Gets notification url.

public getNotificationURL() : string

URL to which BitPay sends webhook notifications. HTTPS is mandatory.

Return values
string

getRecipientId()

Gets BitPay recipient id. Assigned by BitPay for a given recipient email during the onboarding process.

public getRecipientId() : string
Return values
string

getReference()

Gets reference.

public getReference() : string

Present only if specified by the merchant in the request. Merchants can pass their own unique identifier in this field for reconciliation purpose. Maximum string length is 100 characters.

Return values
string

getRequestDate()

Gets date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.

public getRequestDate() : string|null
Return values
string|null

getShopperId()

Gets shopper id.

public getShopperId() : string

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 and payouts).

Return values
string

getStatus()

Gets payout request status.

public getStatus() : string|null

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
Return values
string|null

getToken()

Gets resource token.

public getToken() : string

This token is actually derived from the API token - used to submit the payout and is tied to the specific payout resource id created.

Return values
string

getTransactions()

Gets transactions. Contains the cryptocurrency transaction details for the executed payout request.

public getTransactions() : array<string|int, PayoutTransaction>
Return values
array<string|int, PayoutTransaction>

isIgnoreEmails()

Gets boolean to prevent email updates on a specific payout.

public isIgnoreEmails() : bool

Defaults to false if not provided - you will receive emails unless specified to true.

Return values
bool

setAccountId()

Sets BitPay account id that is associated to the payout, assigned by BitPay for a given account during the onboarding process.

public setAccountId(string $accountId) : void
Parameters
$accountId : string

setAmount()

Sets amount of cryptocurrency sent to the requested address.

public setAmount(float $amount) : void
Parameters
$amount : float

setCode()

Sets error code.

public setCode(int|null $code) : void
Parameters
$code : int|null

setCurrency()

Sets currency code set for the batch amount (ISO 4217 3-character currency code).

public setCurrency(string $currency) : void
Parameters
$currency : string
Tags
throws
BitPayValidationException

setDateExecuted()

Sets date and time (UTC) when BitPay executed the payout. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.

public setDateExecuted(string $dateExecuted) : void
Parameters
$dateExecuted : string

setEffectiveDate()

Sets effective date and time (UTC) for the payout.

public setEffectiveDate(string $effectiveDate) : void

ISO-8601 format yyyy-mm-ddThh:mm:ssZ. If not provided, defaults to date and time of creation.

Parameters
$effectiveDate : string

setEmail()

Sets email.

public setEmail(string $email) : void

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.

Parameters
$email : string

setExchangeRates()

Sets exchange rates keyed by source and target currencies.

public setExchangeRates(array<string|int, mixed> $exchangeRates) : void
Parameters
$exchangeRates : array<string|int, mixed>

setGroupId()

Sets group id.

public setGroupId(string|null $groupId) : void
Parameters
$groupId : string|null

setId()

Sets Payout request id.

public setId(string $id) : void
Parameters
$id : string

setIgnoreEmails()

Sets boolean to prevent email updates on a specific payout.

public setIgnoreEmails(bool $ignoreEmails) : void

Defaults to false if not provided - you will receive emails unless specified to true.

Parameters
$ignoreEmails : bool

setLabel()

Sets label.

public setLabel(string $label) : void

For merchant use, pass through - can be the customer name or unique merchant reference assigned by the merchant to the recipient.

Parameters
$label : string

setLedgerCurrency()

Sets Ledger currency code (ISO 4217 3-character currency code)

public setLedgerCurrency(string $ledgerCurrency) : void

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.

Parameters
$ledgerCurrency : string
Tags
throws
BitPayValidationException

setMessage()

Sets message.

public setMessage(string $message) : void

In case of error, this field will contain a description message. Set to null if the request is successful.

Parameters
$message : string

setNotificationEmail()

Sets notification email.

public setNotificationEmail(string $notificationEmail) : void

Merchant email address for notification of payout status change.

Parameters
$notificationEmail : string

setNotificationURL()

Sets notification url.

public setNotificationURL(string $notificationURL) : void

URL to which BitPay sends webhook notifications. HTTPS is mandatory.

Parameters
$notificationURL : string

setRecipientId()

Sets BitPay recipient id. Assigned by BitPay for a given recipient email during the onboarding process.

public setRecipientId(string $recipientId) : void
Parameters
$recipientId : string

setReference()

Sets reference.

public setReference(string $reference) : void

Present only if specified by the merchant in the request. Merchants can pass their own unique identifier in this field for reconciliation purpose. Maximum string length is 100 characters.

Parameters
$reference : string

setRequestDate()

Sets date and time (UTC) when BitPay received the batch. ISO-8601 format `yyyy-mm-ddThh:mm:ssZ`.

public setRequestDate(string $requestDate) : void
Parameters
$requestDate : string

setShopperId()

Sets shopper id.

public setShopperId(string $shopperId) : void

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 and payouts).

Parameters
$shopperId : string

setStatus()

Sets payout request status.

public setStatus(string $status) : void

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
Parameters
$status : string

setToken()

Sets resource token.

public setToken(string $token) : void

This token is actually derived from the API token - used to submit the payout and is tied to the specific payout resource id created.

Parameters
$token : string

setTransactions()

Sets transactions. Contains the cryptocurrency transaction details for the executed payout request.

public setTransactions(array<string|int, PayoutTransaction> $transactions) : void
Parameters
$transactions : array<string|int, PayoutTransaction>
Tags
throws
PayoutException

toArray()

Return Payout values as array.

public toArray() : array<string|int, mixed>
Return values
array<string|int, mixed> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results