The following API requests allow you to interact with the Payout functionality in Frisbii Billing & Pay.

GET Payout

The Get Payout endpoint in Frisbii Billing & Pay allows you to retrieve detailed information about a specific payout by its unique handle.

This documentation provides instructions on how to make a GET request to this endpoint, interpret the response, and handle potential errors.

API Request

HTTP Method: GET

Endpoint: <https://api.frisbii.com/v1/payout/{handle}>

Arguments:

Name	Type	Description
`handle`	String • Required	The unique reference handle that identifies the payout you want to retrieve.

Response

A successful GET request to the Get Payout endpoint returns a JSON response with detailed information about the specified payout. Here is an example of the JSON structure:

{  
    "handle": "credit-0002",  
    "state": "processing",  
    "amount": 20000,  
    "currency": "USD",  
    "text": "Lottery payout",  
    "customer": "customer006",  
    "paid": "2015-04-04T12:40:56.656+00:00",  
    "failed": "2015-04-04T12:40:56.656+00:00",  
    "created": "2015-04-04T12:40:56.656+00:00",  
    "transactions": [    
        {      
        "id": "dafba2016614418f969fa5697383e47c",      
        "state": "paid",      
        "payout": "payout-1234",      
        "amount": 10000,      
        "paid": "2015-04-04T12:40:56.656+00:00",      
        "failed": "2015-04-04T12:40:56.656+00:00",      
        "created": "2015-04-04T12:40:56.656+00:00",      
        "card": 
            {        
            "id": "ca_fcfac2016614418f969fa5697383e47c",        
            "state": "active",        
            "customer": "customer00069",        
            "reference": "cs_6be90a4babc3c57ef7e6e477ac97ed3b",        
            "failed": "2015-06-04T12:40:56.656+00:00",        
            "created": "2015-04-04T12:40:56.656+00:00",        
            "fingerprint": "cst_64e8a26cc0e85bc3f5ce7c5b366b4096",        
            "reactivated": "2015-05-14T00:00:00.000+00:00",        
            "gw_ref": "657e86162633415a9e6b715248c84da4",        
            "card_type": "visa_dk",        
            "transaction_card_type": "visa",        
            "exp_date": "09-18",        
            "masked_card": "457111XXXXXX3777",        
            "last_success": "2015-05-14T00:00:00.000+00:00",        
            "last_failed": "2015-05-14T00:00:00.000+00:00",        
            "first_fail": "2015-05-14T00:00:00.000+00:00",        
            "error_code": "credit_card_expired",        
            "error_state": "hard_declined",        
            "strong_authentication_status": "secured_by_nets",        
            "three_d_secure_status": "Y",        
            "risk_rule": "",        
            "card_country": "US"      
             },      
        "error": "credit_card_expired",      
        "fingerprint": "cst_64e8a26cc0e85bc3f5ce7c5b366b4096",      
        "provider": "clearhaus",      
        "error_state": "hard_declined",      
        "card_type": "visa",      
        "exp_date": "09-18",      
        "masked_card": "457111XXXXXX3777",      
        "acquirer_code": "40135",      
        "acquirer_message": "Card expired",      
        "acquirer_reference": "Card expired",      
        "text_on_statement": "myshop.com 123"    
         }]
}

The JSON response provides information about the payout, including its state, amount, currency, text, customer details, transaction history, and more.

GET List of Payouts

The Get List of Payouts request in the Frisbii Billing & Pay platform allows you to retrieve a list of payouts based on various criteria. This feature provides valuable insights into the transactions and payouts within your account.

Below, you find detailed information on how to use this request.

HTTP Request

HTTP Method: GET

Endpoint: <https://api.frisbii.com/v1/payouts>

Arguments:

The Get List of Payouts request supports several query parameters to customize the results according to your needs:

Parameter	Type	Description	Example
`from`	String • Query • Required	Defines the time range `from`, inclusive. It uses a local date and time format according to the account's timezone. The default `from` value depends on the query. If the query limits on relation (e.g., customer and/or subscription), the default `from` will be set to epoch time (1970-01-01). Otherwise, it defaults to one month before the current date.	2019-12-01
`to`	String • Query	Specifies the time range `to`, exclusive. It uses a local date and time format according to the account's timezone and defaults to the current time.	2020-01
`interval`	String • Query	Limits `from` and `to` based on an interval back in time. For instance, you can specify an interval like P1W for one week. It takes precedence over `from` and is defined in ISO 8601 duration. See ISO 8601 Durations for more information.	P1W
`size`	Integer • Query	Sets the page size to control the number of results returned in a single response. It should be between 10 and 100, with a default value of 20.	10
`next_page_token`	String • Query	Provides the next page token from a previous response to retrieve the next page of results.	MTYzMjkxNDc4NTAwMDoxMA
`range`	String • Query	Specifies the time and date attribute to time limit, with options for `created` or `paid`. The default value is `created`.	paid
`handle`	String • Query	Filters payouts based on a payout handle prefix.	payout
`handle_contains`	String • Query	Filters payouts based on payout handles that contain the specified text.	123
`customer`	String • Query	Retrieves payouts for a specific customer using their customer handle.	cust-0002
`state`	Array of Strings • Query	Filters payouts based on transaction state. Multiple states can be defined. Available values include: created, processing, paid, failed.	The following A
`amount`	String • Query	Filters payouts based on the amount in the minor unit interval. Refer to the documentation for interval details.	[10000;20000)
`currency`	Array of Strings • Query	Filters payouts based on payout currency in ISO 4217 three-letter alpha code. You can define multiple currencies.	The follow
`card`	String • Query	Retrieves payouts for a saved card using its card handle.	ca_20bce64ffee54a33aecb49bddf5b9d3c
`card_type`	String • Query	Filters payouts based on card type.	visa
`card_prefix`	String • Query	Filters payouts based on a card with a specified prefix.	457100
`card_postfix`	String • Query	Filters payouts based on a card with a specified postfix.	0123
`card_fingerprint`	String • Query	Filters payouts based on a card with a specified fingerprint.	0123

Return

The Get List of Payouts endpoint returns a JSON response with detailed information about the specified payout. Here is an example of the JSON structure:

{
"size": 50,  
"count": 50,  
"to": "2021-10-06T13:02:23.190",  
"from": "2021-09-06T13:02:23.190",  
"content": 
    [    
        {      
            "handle": "credit-0002",      
            "state": "processing",      
            "amount": 20000,      
            "currency": "USD",      
            "text": "Lottery payout",      
            "customer": "customer006",      
            "paid": "2015-04-04T12:40:56.656+00:00",      
            "failed": "2015-04-04T12:40:56.656+00:00",      
            "created": "2015-04-04T12:40:56.656+00:00",      
            "transactions": 
            [        
                {          
                    "id": "dafba2016614418f969fa5697383e47c",          
                    "state": "paid",          
                    "payout": "payout-1234",          
                    "amount": 10000,          
                    "paid": "2015-04-04T12:40:56.656+00:00",          
                    "failed": "2015-04-04T12:40:56.656+00:00",          
                    "created": "2015-04-04T12:40:56.656+00:00",          
                    "card": 
                        {            
                            "id": "ca_fcfac2016614418f969fa5697383e47c",
                            "state": "active",            
                            "customer": "customer00069",            
                            "reference": "cs_6be90a4babc3c57ef7e6e477ac97ed3b",            
                            "failed": "2015-06-04T12:40:56.656+00:00",            
                            "created": "2015-04-04T12:40:56.656+00:00",            
                            "fingerprint": "cst_64e8a26cc0e85bc3f5ce7c5b366b4096",            
                            "reactivated": "2015-05-14T00:00:00.000+00:00",            
                            "gw_ref": "657e86162633415a9e6b715248c84da4",            
                            "card_type": "visa_dk",            
                            "transaction_card_type": "visa",            
                            "exp_date": "09-18",            
                            "masked_card": "457111XXXXXX3777",            
                            "last_success": "2015-05-14T00:00:00.000+00:00",            
                            "last_failed": "2015-05-14T00:00:00.000+00:00",            
                            "first_fail": "2015-05-14T00:00:00.000+00:00",            
                            "error_code": "credit_card_expired",            
                            "error_state": "hard_declined",            
                            "strong_authentication_status": "secured_by_nets",            
                            "three_d_secure_status": "Y",            
                            "risk_rule": "string",            
                            "card_country": "US"          
                            },          
                "error": "credit_card_expired",          
                "fingerprint": "cst_64e8a26cc0e85bc3f5ce7c5b366b4096",          
                "provider": "clearhaus",          
                "error_state": "hard_declined",          
                "card_type": "visa",          
                "exp_date": "09-18",          
                "masked_card": "457111XXXXXX3777",          
                "acquirer_code": "40135",          
                "acquirer_message": "Card expired",          
                "acquirer_reference": "Card expired",          
                "text_on_statement": "myshop.com 123"        
                }]    
            }],  
"next_page_token": "MTYzMjkxNDc4NTAwMDoxMA"
}

The Get List of Payouts request in the Frisbii Billing & Pay platform empowers you to retrieve and analyze payouts within your account based on various filters, providing insights into your financial transactions.

POST Create Payout

The Create Payout endpoint in Frisbii Billing & Pay allows you to initiate the process of transferring funds to your customers through saved Visa or Mastercard-branded cards.

This documentation provides an in-depth guide on how to utilize this feature efficiently and handle various aspects of the process, including response interpretation and error handling.

HTTP Request

HTTP Method: POST

Endpoint: [https://api.frisbii.com/v1/payouts](https://api.reepay.com/v1/payout)

Arguments:

The endpoint accepts the following arguments:

Name	Type	Description
`handle`	String • Required	A unique reference specific to your Frisbii account for this payout. It is crucial to ensure that this handle is a maximum of 255 characters and recommended being kept within 20 characters to avoid truncation on bank statements.
`destination`	String • Required	Specifies the destination for the payout, which can be either an existing payment method for the customer or a card token.
`amount`	Integer • Required	The payout amount, measured in the smallest currency unit. It is mandatory if a charge or invoice does not already exist.
`currency`	String • Optional	An optional field to specify the currency for the payout in ISO 4217 three-letter alpha code. If not provided, the account's default currency will be used.
`text`	String • Optional	An optional field to include text associated with the payout.
`customer`	CreateCustomer • Optional	This is an alternative to using a reference to an already created customer. It is an object that contains various customer details. If this object is provided and the customer already exists, the existing customer will be used. It is important to note that the customer cannot be changed for an existing payout, so the handle must match the customer handle for an existing customer.
`customer_handle`	String • Optional	Customer reference, which is required if the payout does not already exist. This reference must be provided, or a `CreateCustomer` object must be provided, or the destination must be a payment method reference (e.g., ca_...) identifying the customer. Like the customer field, the customer handle cannot be changed for an existing payout, and the provided handle must match the customer handle for the existing customer.
`text_on_statement`	String • Optional	An optional argument that allows you to define the text that will appear on the customer's bank statement. This text should match the regex pattern isbii Billi.
`acquirer_reference`	String • Optional	This is an optional reference for the transaction at the acquirer. It is important to note the following regarding this argument: It may only work for some acquirers. Acquirers may have rigid rules regarding the content of the acquirer reference.🚧 Caution 🚧Not adhering to these rules can result in declined payments. It is possible to define custom acquirer references using templating in the Frisbii Administration, and it is recommended to contact support for assistance. The maximum length for this reference is 128 characters, but most acquirers require a maximum length of 22 characters. Truncation will be applied if it is too long for a specific acquirer.The characters must match the regex pattern \| `handle` .

Response

Upon a successful request, the response is an HTTP 200 status code.

However, it is important to note that this status code relates to the communication with Frisbii and their ability to process the request, not necessarily the outcome of the payout.

The actual result of the payout operation should be determined by examining the state parameter.

{  
    "handle": "credit-0002",  
    "destination": "ca_f96004cae4308473c92bea0638b5b688",  
    "amount": 20000,  
    "currency": "USD",  
    "text": "Lottery payout",  
    "customer": 
    {    
        "email": "[email protected]",    
        "address": "Grove Street 12",    
        "address2": "Ganton",    
        "city": "Los Santos",    
        "country": "US",    
        "phone": "555-gotcars",    
        "company": "Leones Cars",    
        "vat": "US123456789",    
        "handle": "customer006",    
        "test": true,    
        "metadata": {},    
        "first_name": "Carl",    
        "last_name": "Johnson",    
        "postal_code": "4531",    
        "generate_handle": true  
    },  
    "customer_handle": "cust-0022",  
    "text_on_statement": "myshop.com 23",  
    "acquirer_reference": ""
}

State Parameter

Name	Type	Description
`state`	String	This parameter indicates the current state of the payout. The possible states include: `paid` `failed` `processing`📘 Note 📘 For asynchronous payment methods, a `processing` state may indicate that the result of the payout will be delivered via a webhook.

Name

Type

Description

state

String

This parameter indicates the current state of the payout. The possible states include:

paid
failed
processing📘 Note 📘
For asynchronous payment methods, a processing state may indicate that the result of the payout will be delivered via a webhook.

Error Handling

Error handling is a critical aspect of using the Create Payout endpoint, as it involves financial transactions. The documentation provides clear guidance on how to handle different types of errors:

Error Type	Description
Communication Error (No HTTP Response) or HTTP Server Error (5xx)	In case of a communication error or a server error with a 5xx status code, it is recommended to retry the operation immediately or later. Retrying is crucial as the payout operation may have already gone through, potentially resulting in the movement of money.
HTTP Client Error (4xx)	If you encounter a 4xx status code, it is essential to check your implementation for any issues.
Other Non-200 HTTP Response	In the case of a non-200 HTTP response, something may be wrong. It should be handled similarly to a communication error, and if the issue persists, it is advisable to contact our support for assistance.
`state` = `paid`	If the state is `paid`, the operation is considered successful.
`state` = `processing`	A `processing` state indicates success for payment types with asynchronous payouts. The result of the refund will be delivered through a webhook.
`error_state` = `hard_declined`	If the error state is `hard_declined`, it means the refund operation has been declined by the acquirer or issuer. Further attempts with the same arguments are unlikely to succeed.
`error_state` = `processing_error`	A `processing_error` can occur in certain situations where there is an issue during the processing of the payout. 📘 Note 📘 In such cases, it is essential to investigate the specific error details and take appropriate corrective actions to ensure successful payouts.

The Create Payout endpoint's error handling mechanism plays a crucial role in maintaining the integrity and security of financial transactions.

🚧
Caution
It is important to monitor, interpret, and respond to errors promptly to ensure a smooth payout process.