Fundamentals
Customers
Charges
Payouts
Payments
Embed
- Organizations
- Accounts
- Representatives
- Linked Bank Accounts
- Capability Requests
Hold a payout
Hold a payout to prevent it from being processed. The status of the payout must be created, scheduled, or on_hold.
import Straddle from '@straddleio/straddle';
const client = new Straddle({
apiKey: process.env['STRADDLE_API_KEY'], // This is the default and can be omitted
});
async function main() {
const payoutV1 = await client.payouts.hold('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { reason: 'reason' });
console.log(payoutV1.data);
}
main();{
"meta": {
"api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"api_request_timestamp": "2023-11-07T05:31:56Z"
},
"response_type": "object",
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"paykey": "<string>",
"description": "<string>",
"payment_rail": "ach",
"customer_details": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Ron Swanson",
"customer_type": "individual",
"email": "ron@swanson.com",
"phone": "+1234567890"
},
"paykey_details": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Bank of America ****1234",
"balance": "100.00"
},
"amount": "10000",
"currency": "USD",
"payment_date": "2023-12-25",
"device": {
"ip_address": "192.168.1.1"
},
"external_id": "<string>",
"config": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"processed_at": "2023-11-07T05:31:56Z",
"effective_at": "2023-11-07T05:31:56Z",
"status": "created",
"status_details": {
"message": "Payment successfully created and awaiting validation.",
"reason": "OK",
"source": "system",
"changed_at": "2023-11-07T05:31:56Z",
"code": null
},
"status_history": [
{
"reason": "insufficient_funds",
"source": "watchtower",
"message": "Payment successfully created and awaiting validation.",
"code": null,
"changed_at": "2023-11-07T05:31:56Z",
"status": "created"
}
],
"metadata": {},
"funding_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
}Authorizations
Use your Straddle API Key in the Authorization header as Bearer <token> to authorize API requests.
Headers
For use by platforms to specify an account id and set scope of a request.
Optional client generated identifier to trace and debug a request.
Optional client generated identifier to trace and debug a series of requests.
Path Parameters
Body
Details about why the payout status was updated.
Response
Indicates the structure of the returned content.
- "object" means the
datafield contains a single JSON object. - "array" means the
datafield contains an array of objects. - "error" means the
datafield contains an error object with details of the issue. - "none" means no data is returned.
object, array, error, none Unique identifier for the payout.
Value of the paykey used for the payout.
An arbitrary description for the payout.
The amount of the payout in cents.
"10000"
The currency of the payout. Only USD is supported.
The desired date on which the payment should be occur. For payouts, this means the date you want the funds to be sent from your bank account.
Information about the device used when the customer authorized the payout.
The IP address of the device used when the customer authorized the charge or payout. Use 0.0.0.0 to represent an offline consent interaction.
"192.168.1.1"
Unique identifier for the payout in your database. This value must be unique across all payouts.
Configuration for the payout.
The current status of the payout.
created, scheduled, failed, cancelled, on_hold, pending, paid, reversed Details about the current status of the payout.
A human-readable description of the current status.
"Payment successfully created and awaiting validation."
A machine-readable identifier for the specific status, useful for programmatic handling.
insufficient_funds, closed_bank_account, invalid_bank_account, invalid_routing, disputed, payment_stopped, owner_deceased, frozen_bank_account, risk_review, fraudulent, duplicate_entry, invalid_paykey, payment_blocked, amount_too_large, too_many_attempts, internal_system_error, user_request, ok, other_network_return, payout_refused Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.
watchtower, bank_decline, customer_dispute, user_action, system The time the status change occurred.
The status code if applicable.
null
History of the status changes for the payout.
A machine-readable identifier for the specific status, useful for programmatic handling.
insufficient_funds, closed_bank_account, invalid_bank_account, invalid_routing, disputed, payment_stopped, owner_deceased, frozen_bank_account, risk_review, fraudulent, duplicate_entry, invalid_paykey, payment_blocked, amount_too_large, too_many_attempts, internal_system_error, user_request, ok, other_network_return, payout_refused Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.
watchtower, bank_decline, customer_dispute, user_action, system A human-readable description of the status.
"Payment successfully created and awaiting validation."
The time the status change occurred.
The current status of the charge or payout.
created, scheduled, failed, cancelled, on_hold, pending, paid, reversed The status code if applicable.
null
Funding Ids
The payment rail used for the payout.
ach Information about the customer associated with the payout.
Unique identifier for the customer
The name of the customer
"Ron Swanson"
The type of customer
individual, business The customer's email address
"ron@swanson.com"
The customer's phone number in E.164 format
"+1234567890"
Information about the paykey used for the payout.
Unique identifier for the paykey.
Unique identifier for the customer associated with the paykey.
Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI
"Bank of America ****1234"
The most recent balance of the bank account associated with the paykey in dollars.
"100.00"
The time the payout was created.
The time the payout was last updated.
The time the payout was processed by Straddle and originated to the payment rail.
The actual date on which the payment occurred. For payouts, this is the date the funds were sent from your bank account.
import Straddle from '@straddleio/straddle';
const client = new Straddle({
apiKey: process.env['STRADDLE_API_KEY'], // This is the default and can be omitted
});
async function main() {
const payoutV1 = await client.payouts.hold('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { reason: 'reason' });
console.log(payoutV1.data);
}
main();{
"meta": {
"api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"api_request_timestamp": "2023-11-07T05:31:56Z"
},
"response_type": "object",
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"paykey": "<string>",
"description": "<string>",
"payment_rail": "ach",
"customer_details": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Ron Swanson",
"customer_type": "individual",
"email": "ron@swanson.com",
"phone": "+1234567890"
},
"paykey_details": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Bank of America ****1234",
"balance": "100.00"
},
"amount": "10000",
"currency": "USD",
"payment_date": "2023-12-25",
"device": {
"ip_address": "192.168.1.1"
},
"external_id": "<string>",
"config": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"processed_at": "2023-11-07T05:31:56Z",
"effective_at": "2023-11-07T05:31:56Z",
"status": "created",
"status_details": {
"message": "Payment successfully created and awaiting validation.",
"reason": "OK",
"source": "system",
"changed_at": "2023-11-07T05:31:56Z",
"code": null
},
"status_history": [
{
"reason": "insufficient_funds",
"source": "watchtower",
"message": "Payment successfully created and awaiting validation.",
"code": null,
"changed_at": "2023-11-07T05:31:56Z",
"status": "created"
}
],
"metadata": {},
"funding_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
}