API Requests
The following API requests allow you to interact with the Payout functionality in Billwerk+.
GET Payout
The Get Payout endpoint in Billwerk+ 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.reepay.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 Billwerk+ 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.reepay.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. | [paid, created] |
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. | [USD, EUR] |
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 Billwerk+ 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 Billwerk+ 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.reepay.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 Billwerk+ 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 [\x20-\x7F]. |
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 Billwerk+ 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 [\x20-\x7F]. |
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 Billwerk+ 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. |
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.
Updated 9 months ago