Create payout

post

https://api.frisbii.com/v1/payout

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

The response is a HTTP 200 if the request is understood and processed by Frisbii Billing and Pay, but not necessarily with success. The HTTP status code relates to the communication with Frisbii Billing and Pay and Frisbii Billing and Pays ability to process the request, not the result of the payout. The result of the payout operation should be determined from the state parameter which will be paid, failed or processing (only asynchronous payment methods). The error state and error reason can be found in error_state and error parameters of the latest payout transaction.

Error handling if a payout operation fails is important, as this is a money carrying operation.

Error	Handling
`Communication error (no HTTP respoonse)` `or HTTP server error 5xx`	Retry operation immediately or later. Retry is important as the refund operation can actually have gone through so money has been moved.
`HTTP client error 4xx`	Check your implementation.
`Other non 200 HTTP response`	Something is wrong. Handle as for communication error and contact Frisbii Billing and Pay if the problem persists.
`state = paid`	Success
`state = processing`	Success - The payment type has asynchronous payouts. The result of the refund will be deliverd in webhook.
`error_state = hard_declined`	The refund operation has been declined by acquirer or issuer. No further attempts with same arguments will succeed.
`error_state = processing_error`	A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in an approved payout, but the result never reaches Frisbii Billing and Pay. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare. We recommend to retry later on a processing error, but only a few times.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Error code	HTTP code	Description
`40`	`404`	Payment method not found
`135`	`400`	Payment method not allowed for payout
`136`	`400`	Customer cannot be changed for payout attempt on previously failed payout

Body Params

handle

string

required

length ≥ 1

Per account unique reference to payout. Max length 255 with allowable characters [a-zA-Z0-9_.-@]. It is recommended to use a maximum of 20 characters as this will allow for the use of handle as reference on bank statements without truncation.

destination

string

required

length ≥ 1

The destination for the payout. Either an existing payment method for the customer or a card token.

amount

int32

required

≥ 1

Amount in the smallest unit. Must be provided if charge/invoice does not already exists.

currency

string

Optional currency in ISO 4217 three letter alpha code. If not provided the account default currency will be used.

text

string

Optional text associated with the payout

customer

object

Create customer object

customer_handle

string

Customer reference. If payout does not already exist either this reference must be provided, a create customer object must be provided or the destination must be a payment method reference (e.g. ca_..) identifying customer. Notice that customer cannot be changed for existing payout so if handle is provided it must match the customer handle for existing customer.

text_on_statement

string

Optional argument to define the text on bank statement. Characters must match regex [\x20-\x7F]

acquirer_reference

string

Optional reference for the transaction at the acquirer. Notice the following about this argument:

It only works for some acquirers.
Acquirers may have rigid rules on the content of the acquirer reference.
Not complying to these rules can result in declined payments.
It is already possible to define custom acquirer reference using templating in the Frisbii Administration.
Contact support for help. We highly recommend to only supply this argument if absolutely necessary,
and the templated default acquirer reference is not sufficient. Maximum length is 128,
but most acquirers require a maximum length of 22 characters.
Truncating will be applied if too long for specific acquirer.
Characters must match regex [\x20-\x7F]

Responses

Errors

200Successful operation

400Invalid request, see error codes at https://api.frisbii.com/v1/error_codes

401None or invalid credentials provided in access to secured resource

403Not authorized to perform resource operation

404Resource or referenced resource not found, see error codes at https://api.frisbii.com/v1/error_codes

429Request limiting exceeded, request rate or concurrent requests, see error code 122 and 123

500Internal service error, error is reported automatically to Frisbii