Payabli payoutSubscription API
The payoutSubscription API from Payabli — 2 operation(s) for payoutsubscription.
OpenAPI Specification
openapi: 3.1.0
info:
title: API reference Bill payoutSubscription API
version: 1.0.0
servers:
- url: https://api-sandbox.payabli.com/api
description: Sandbox
- url: https://api.payabli.com/api
description: Production
tags:
- name: payoutSubscription
paths:
/PayoutSubscription:
post:
operationId: CreatePayoutSubscription
summary: Create payout subscription
description: Creates a payout subscription to automatically send payouts to a vendor on a recurring schedule. See [Manage payout subscriptions](/guides/pay-out-developer-payout-subscriptions-manage) for a step-by-step guide.
tags:
- payoutSubscription
parameters:
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
- name: idempotencyKey
in: header
description: _Optional but recommended_ A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn't generated in Payabli, you must generate it yourself. This key persists for 2 minutes. After 2 minutes, you can reuse the key if needed.
required: false
schema:
$ref: '#/components/schemas/IdempotencyKey'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AddPayoutSubscriptionResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutSubscriptionRequestBody'
/PayoutSubscription/{id}:
get:
operationId: GetPayoutSubscription
summary: Get a payout subscription
description: Retrieves a single payout subscription's details. See [Manage payout subscriptions](/guides/pay-out-developer-payout-subscriptions-manage) for more information.
tags:
- payoutSubscription
parameters:
- name: id
in: path
description: The payout subscription ID.
required: true
schema:
type: integer
format: int64
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetPayoutSubscriptionResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
put:
operationId: UpdatePayoutSubscription
summary: Update a payout subscription
description: Updates a payout subscription's details. See [Manage payout subscriptions](/guides/pay-out-developer-payout-subscriptions-manage) for more information.
tags:
- payoutSubscription
parameters:
- name: id
in: path
description: The payout subscription ID.
required: true
schema:
type: integer
format: int64
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePayoutSubscriptionResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePayoutSubscriptionBody'
delete:
operationId: DeletePayoutSubscription
summary: Delete a payout subscription
description: Deletes a payout subscription and prevents future payouts. See [Manage payout subscriptions](/guides/pay-out-developer-payout-subscriptions-manage) for more information.
tags:
- payoutSubscription
parameters:
- name: id
in: path
description: The payout subscription ID.
required: true
schema:
type: integer
format: int64
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeletePayoutSubscriptionResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
components:
schemas:
AddPayoutSubscriptionResponse:
type: object
properties:
isSuccess:
$ref: '#/components/schemas/IsSuccess'
responseText:
$ref: '#/components/schemas/ResponseText'
responseData:
type: integer
description: The identifier of the newly created payout subscription.
customerId:
$ref: '#/components/schemas/CustomerId'
description: The identifier of the vendor associated with the payout subscription.
required:
- responseText
- responseData
description: Success response
title: AddPayoutSubscriptionResponse
ContactsField:
type: array
items:
$ref: '#/components/schemas/Contacts'
description: List of contacts.
title: ContactsField
AccountId:
type: string
description: Custom identifier for payment connector.
title: AccountId
Maskedaccount:
type: string
description: 'Masked card or bank account used in transaction. In the case of Apple
Pay, this is a masked DPAN (device primary account number).
'
title: Maskedaccount
BankName:
type: string
description: Name of bank for account.
title: BankName
PayoutScheduleDetail:
type: object
properties:
startDate:
type: string
description: 'Subscription start date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY. This must be a future date.'
endDate:
type: string
description: 'Subscription end date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY or the value `untilcancelled` to indicate a scheduled payout with infinite cycle.'
frequency:
$ref: '#/components/schemas/Frequency'
description: Frequency of the payout subscription.
title: PayoutScheduleDetail
PayabliErrorBodyResponseData:
type: object
properties:
explanation:
type: string
description: Human-readable explanation of what happened.
todoAction:
type: string
description: Suggested resolution.
description: Object with detailed error context.
title: PayabliErrorBodyResponseData
Email:
type: string
format: email
description: Email address.
title: Email
Accountexp:
type: string
description: Expiration date of card used in transaction.
title: Accountexp
CityNullable:
type: string
description: The city.
title: CityNullable
RequestOutAuthorizeVendorData:
type: object
properties:
vendorNumber:
$ref: '#/components/schemas/VendorNumber'
name1:
$ref: '#/components/schemas/VendorName1'
name2:
$ref: '#/components/schemas/VendorName2'
ein:
$ref: '#/components/schemas/VendorEin'
phone:
$ref: '#/components/schemas/VendorPhone'
email:
$ref: '#/components/schemas/Email'
address1:
$ref: '#/components/schemas/AddressNullable'
city:
type: string
state:
type: string
zip:
type: string
country:
type: string
mcc:
$ref: '#/components/schemas/Mcc'
contacts:
$ref: '#/components/schemas/ContactsField'
billingData:
$ref: '#/components/schemas/RequestOutAuthorizeVendorBillingData'
vendorStatus:
$ref: '#/components/schemas/Vendorstatus'
remitAddress1:
$ref: '#/components/schemas/Remitaddress1'
remitAddress2:
$ref: '#/components/schemas/Remitaddress2'
remitCity:
$ref: '#/components/schemas/Remitcity'
remitState:
$ref: '#/components/schemas/Remitstate'
remitZip:
$ref: '#/components/schemas/Remitzip'
remitCountry:
$ref: '#/components/schemas/Remitcountry'
customerVendorAccount:
type: string
customField1:
type: string
customField2:
type: string
additionalData:
$ref: '#/components/schemas/AdditionalData'
address2:
$ref: '#/components/schemas/AddressAddtlNullable'
internalReferenceId:
type: integer
format: int64
locationCode:
$ref: '#/components/schemas/LocationCode'
payeeName1:
$ref: '#/components/schemas/PayeeName'
payeeName2:
$ref: '#/components/schemas/PayeeName'
paymentMethod:
$ref: '#/components/schemas/VendorPaymentMethod'
vendorId:
$ref: '#/components/schemas/Vendorid'
description: Object containing vendor data.
title: RequestOutAuthorizeVendorData
RemitEmail:
type: string
format: email
description: 'Remittance email address. Used for sending virtual cards and other
information about payouts.
'
title: RemitEmail
PayeeName:
type: string
description: Alternative name used to receive paper check.
title: PayeeName
Entrypointfield:
type: string
description: The entrypoint identifier.
title: Entrypointfield
IdempotencyKey:
type: string
description: '_Optional but recommended._ A unique ID that you can include to prevent
duplicating objects or transactions in the case that a request is sent
more than once. This key isn''t generated in Payabli; you must generate it
yourself. The key persists for 2 minutes. After 2 minutes, you can reuse
the key if needed.
'
title: IdempotencyKey
Vendorid:
type: integer
description: Payabli identifier for vendor record.
title: Vendorid
FileContent:
type: object
properties:
fContent:
type: string
description: 'Content of file, Base64-encoded. Ignored if `furl` is specified. Max
upload size is 30 MB.
'
filename:
type: string
description: The name of the attached file.
ftype:
$ref: '#/components/schemas/FileContentFtype'
furl:
type: string
description: Optional URL provided to show or download the file remotely.
description: Contains details about a file. Max upload size is 30 MB.
title: FileContent
AchSecCode:
type: string
description: "Standard Entry Class (SEC) code is a three letter code that describes\nhow an ACH payment was authorized. Supported values are:\n\n- **PPD** (Prearranged Payment and Deposit) — Used for credits or debits\n where an accountholder authorizes a company to initiate either a single\n or recurring transaction to their personal bank account. Common examples\n include direct deposit of payroll, mortgage payments, or utility bills.\n This is the default value for subscription payments.\n- **WEB** (Internet-Initiated/Mobile Entry) — Used for debit entries when\n authorization is obtained from an accountholder via the internet or a\n wireless network. Common examples are online bill payments, ecommerce\n purchases, and mobile app payments where the consumer enters their\n banking information online.\n- **TEL** (Telephone-Initiated Entry) — Used for one-time debit entries\n where authorization is obtained from a consumer via telephone. Common\n examples are phone-based purchases or bill payments where the consumer\n provides their banking information over the phone.\n- **CCD** (Corporate Credit or Debit) — Used for fund transfers between\n business accounts. This code is specifically for business-to-business\n transactions. Common examples include vendor payments and other\n business-to-business payments.\n- **BOC** (Back Office Conversion) — Used to convert paper checks received\n in-person at a point-of-sale or staffed payment location into electronic\n ACH debits. Required for Remote Deposit Capture (RDC) transactions. Only\n supports consumer checks; business, government, and mailed checks\n aren't eligible.\n"
title: AchSecCode
CreatedAt:
type: string
format: date-time
description: Timestamp of when record was created, in UTC.
title: CreatedAt
BinData:
type: object
properties:
binMatchedLength:
type: string
description: 'The number of characters from the beginning of the card number that
were matched against a Bank Identification Number (BIN) or the Card
Range table.'
binCardBrand:
type: string
description: 'The card brand. For example, Visa, Mastercard, American Express,
Discover.'
binCardType:
type: string
description: 'The type of card: `Credit` or `Debit`. Case can vary between
processors, so compare this value case-insensitively.'
binCardCategory:
type: string
description: 'The category of the card, which indicates the card product. For example: Standard, Gold, Platinum, etc. The binCardCategory for prepaid cards is marked `PREPAID`.'
binCardIssuer:
type: string
description: The name of the financial institution that issued the card.
binCardIssuerCountry:
type: string
description: The issuing financial institution's country name.
binCardIssuerCountryCodeA2:
type: string
description: The issuing financial institution's two-character ISO country code. See [this resource](https://www.iso.org/obp/ui/#search) for a list of codes.
binCardIssuerCountryNumber:
type: string
description: The issuing financial institution's ISO standard numeric country code. See [this resource](https://www.iso.org/obp/ui/#search) for a list of codes.
binCardIsRegulated:
type: string
description: Indicates whether the card is regulated.
binCardUseCategory:
type: string
description: The use category classification for the card.
binCardIssuerCountryCodeA3:
type: string
description: 'The issuing financial institution''s three-character ISO country code.
See [this resource](https://www.iso.org/obp/ui/#search) for a list of
codes.'
description: 'Object containing information related to the card. This object is `null`
unless the payment method is card. If the payment method is Apple Pay, the
binData will be related to the DPAN (device primary account number), not
the card connected to Apple Pay.'
title: BinData
Holdername:
type: string
description: The cardholder name.
title: Holdername
ResponseText:
type: string
description: 'Response text for operation: ''Success'' or ''Declined''.
'
title: ResponseText
VendorPhone:
type: string
description: 'Vendor''s phone number. Phone number can''t contain non-digit characters
like hyphens or parentheses.
'
title: VendorPhone
AchHolderType:
type: string
enum:
- personal
- business
default: personal
description: 'The bank''s accountholder type: personal or business.
'
title: AchHolderType
RequestOutAuthorizeVendorBillingData:
type: object
properties:
bankName:
$ref: '#/components/schemas/BankName'
routingAccount:
$ref: '#/components/schemas/RoutingAccount'
accountNumber:
$ref: '#/components/schemas/AccountNumber'
typeAccount:
$ref: '#/components/schemas/TypeAccount'
bankAccountHolderName:
$ref: '#/components/schemas/BankAccountHolderName'
description: Object containing vendor's bank information. This object is deprecated for this endpoint. Use the `paymentMethod` object in payout authorize requests instead.
title: RequestOutAuthorizeVendorBillingData
BillPayOutData:
type: object
properties:
billId:
type: integer
format: int64
description: Bill ID in Payabli.
LotNumber:
type:
- string
- 'null'
description: Lot number associated with the bill.
AccountingField1:
$ref: '#/components/schemas/AccountingField'
AccountingField2:
$ref: '#/components/schemas/AccountingField'
Terms:
$ref: '#/components/schemas/Terms'
description: Description of payment terms.
AdditionalData:
$ref: '#/components/schemas/AdditionalDataString'
attachments:
$ref: '#/components/schemas/Attachments'
description: Bill image attachment. Send the bill image as Base64-encoded string, or as a publicly accessible link. For full details on using this field with a payout authorization, see [the documentation](/developers/developer-guides/pay-out-manage-payouts).
invoiceNumber:
$ref: '#/components/schemas/InvoiceNumber'
description: Custom number identifying the bill. Must be unique in paypoint. **Required** for new bill and when `billId` isn't provided.
netAmount:
$ref: '#/components/schemas/NetAmountstring'
description: Net Amount owed in bill. Required when adding a bill.
invoiceDate:
type:
- string
- 'null'
format: date
description: Bill date in format YYYY-MM-DD or MM/DD/YYYY.
dueDate:
type:
- string
- 'null'
format: date
description: Bill due date in format YYYY-MM-DD or MM/DD/YYYY.
comments:
$ref: '#/components/schemas/Comments'
description: Any comments about bill. **For managed payouts, this field has a limit of 100 characters**.
identifier:
type:
- string
- 'null'
description: Custom identifier for the bill.
discount:
type: string
description: Bill discount amount.
totalAmount:
type:
- string
- 'null'
description: Total amount of the bill.
required:
- invoiceDate
- dueDate
title: BillPayOutData
Initiator:
type: string
description: 'The transaction''s initiator. Indicates who initiated the transaction.
'
title: Initiator
Remitcountry:
type: string
description: 'Remittance address country. Used for mailing paper checks. Must be `US`
or `CA`. Defaults to `US` if not provided.
'
title: Remitcountry
EnrollmentStatus:
type: string
description: Enrollment status of vendor in payables program.
title: EnrollmentStatus
CustomerId:
type: integer
format: int64
description: The Payabli-generated unique ID for the customer.
title: CustomerId
InternalReferenceId:
type: integer
format: int64
description: An internal reference ID.
title: InternalReferenceId
VendorName2:
type: string
description: 'Secondary name for vendor. If provided, allowed characters are the
same as the `name1` field.
'
title: VendorName2
Subdomain:
type: string
description: 'Refers to the payment page identifier. If provided, then the
transaction is linked to the payment page.
'
title: Subdomain
Comments:
type: string
description: Any comment or description.
title: Comments
PayabliErrorBody:
type: object
properties:
isSuccess:
type: boolean
description: Always `false` for error responses.
responseCode:
type: integer
description: 'Code for the response. Learn more in
[API Response Codes](/developers/api-reference/api-responses).
'
responseText:
type: string
description: Error text describing what went wrong.
responseData:
$ref: '#/components/schemas/PayabliErrorBodyResponseData'
description: Object with detailed error context.
required:
- isSuccess
- responseText
description: 'Shape returned by every Payabli API error response. The `responseData`
object carries human-readable error context.
'
title: PayabliErrorBody
PayoutSubscriptionRequestBody:
type: object
properties:
entryPoint:
$ref: '#/components/schemas/Entrypointfield'
subdomain:
$ref: '#/components/schemas/Subdomain'
accountId:
$ref: '#/components/schemas/AccountId'
source:
$ref: '#/components/schemas/Source'
setPause:
$ref: '#/components/schemas/PayoutSetPause'
paymentMethod:
$ref: '#/components/schemas/AuthorizePaymentMethod'
description: Payment method for the payout subscription. Supports `ach`, `vcard`, and `check`. The `managed` method isn't supported for payout subscriptions.
paymentDetails:
$ref: '#/components/schemas/PayoutPaymentDetail'
description: Object describing details of the payout.
vendorData:
$ref: '#/components/schemas/RequestOutAuthorizeVendorData'
description: Object identifying the vendor for this subscription. Only a `vendorId` or `vendorNumber` is needed to link to an existing vendor.
billData:
type: array
items:
$ref: '#/components/schemas/BillPayOutDataRequest'
description: Array of bills associated with the payout subscription. If omitted and `doNotCreateBills` isn't set to `true`, the system creates a bill automatically.
scheduleDetails:
$ref: '#/components/schemas/PayoutScheduleDetail'
description: Object describing the schedule for the payout subscription.
required:
- entryPoint
- paymentMethod
- vendorData
title: PayoutSubscriptionRequestBody
Vendorstatus:
type: integer
description: 'Vendor''s status. Allowed values:
- `0` Inactive
- `1` Active
- `-99` Deleted
'
title: Vendorstatus
BankAccountHolderType:
type: string
enum:
- Personal
- Business
description: Describes whether the bank is a personal or business account.
title: BankAccountHolderType
PaypointId:
type: integer
format: int64
description: The paypoint's ID. Note that this is different than the entryname.
title: PaypointId
PayoutPaymentDetail:
type: object
properties:
totalAmount:
type: number
format: double
description: Total payout amount. If a service fee is included, this amount should include the service fee.
serviceFee:
type: number
format: double
description: Service fee to be deducted from the total amount. This amount must be a number, percentages aren't accepted.
currency:
type: string
description: Currency code ISO-4217. If no code is provided, the currency in the paypoint setting is used. Default is `USD`.
checkNumber:
type: string
description: A check number for the payout. Required when the payment method is `check`.
orderDescription:
type: string
description: Description of the payout order.
orderId:
type: string
description: Order identifier associated with the payout.
orderIdAlternative:
type: string
description: Alternative order identifier.
paymentDescription:
type: string
description: Description of the payment.
settlementDescriptor:
type: string
description: Settlement descriptor for the payout.
groupNumber:
type: string
description: Group number for the payout.
source:
type: string
description: Source identifier for the payout.
payabliTransId:
type: string
description: Payabli transaction identifier.
unbundled:
type: boolean
description: When `true`, each bill is processed as a separate payout. When `false` or not provided, multiple bills are paid with a single payout.
required:
- totalAmount
description: Payment details for payout subscriptions.
title: PayoutPaymentDetail
VendorPaymentMethod:
type: object
properties:
method:
type: string
description: Payment method type - "managed", "vcard", "check", or "ach"
storedMethodId:
type: string
description: ID of the stored ACH payment method. Only applicable when method is "ach". Required when using a previously saved ACH method when the vendor has more than one saved method. See the [Payouts with saved ACH payment methods](/developers/developer-guides/pay-out-manage-payouts) section for more details.
required:
- method
description: 'Payment method object to use for the payout.
- `{ method: "managed" }` - Managed payment method
- `{ method: "vcard" }` - Virtual card payment method
- `{ method: "check" }` - Check payment method
- `{ method: "ach", storedMethodId?: "..." }` - ACH payment method with optional stored method ID'
title: VendorPaymentMethod
LocationCode:
type: string
description: A location code used to identify the vendor's location.
title: LocationCode
PayoutSetPause:
type: boolean
description: Flag indicating if the payout subscription is paused. When a payout subscription is paused, no payouts are processed until it's unpaused, and the next payment date isn't calculated automatically.
title: PayoutSetPause
AdditionalDataString:
type: string
description: "Custom dictionary of key:value pairs. You can use this field to store any\ndata related to the object or for your system. Example usage:\n\n```json\n{\n \"additionalData\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\",\n \"key3\": \"value3\"\n }\n}\n```\n"
title: AdditionalDataString
RoutingAccount:
type: string
description: Routing number of bank account.
title: RoutingAccount
VendorEin:
type: string
description: 'EIN/Tax ID for vendor. Must be nine digits formatted as `XX-XXXXXXX`
(for example, `12-3456789`).
'
title: VendorEin
GeneralEvents:
type: object
properties:
description:
type: string
description: Event description.
eventTime:
type: string
format: date-time
description: Event timestamp, in UTC.
extraData:
type:
- string
- 'null'
description: Extra data.
refData:
type: string
description: Reference data.
source:
$ref: '#/components/schemas/Source'
description: The event source.
title: GeneralEvents
IsSuccess:
type: boolean
description: 'Boolean indicating whether the operation was successful. A `true` value
indicates success. A `false` value indicates failure.
'
title: IsSuccess
Ein:
type: string
description: Business EIN or tax ID. This value is masked in API responses.
title: Ein
Dbaname:
type: string
description: 'The alternate or common name that this business is doing business under,
usually referred to as a DBA name.
'
title: Dbaname
BillingDataResponse:
type: object
properties:
id:
type: integer
description: The bank's ID in Payabli.
accountId:
$ref: '#/components/schemas/AccountId'
description: An identifier for the bank account. If not provided during creation or update, the system generates one in the format `acct-{first_digit}xxxxx{last_4_digits}` based on the account number. If a duplicate exists within the same service at the paypoint, a numeric suffix is appended, such as `-2`. This value is also used as the identifier for the bank account's associated payment connector.
nickname:
type: string
bankName:
$ref: '#/components/schemas/BankName'
routingAccount:
$ref: '#/co
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/payabli/refs/heads/main/openapi/payabli-payoutsubscription-api-openapi.yml