Payabli chargeBacks API
The chargeBacks API from Payabli — 3 operation(s) for chargebacks.
OpenAPI Specification
openapi: 3.1.0
info:
title: API reference Bill chargeBacks 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: chargeBacks
paths:
/ChargeBacks/read/{Id}:
get:
operationId: GetChargeback
summary: Get chargeback or ACH return record
description: Retrieves a chargeback record and its details.
tags:
- chargeBacks
parameters:
- name: Id
in: path
description: ID of the chargeback or return record. This is returned as `chargebackID` in the [ReceivedChargeBack](/guides/pay-ops-webhooks-payloads#receivedchargeback) and [ReceivedAchReturn](/guides/pay-ops-webhooks-payloads#receivedachreturn) webhook notifications.
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/ChargebackQueryRecords'
'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'
/ChargeBacks/response/{Id}:
post:
operationId: AddResponse
summary: Add response to chargeback or return
description: Add a response to a chargeback or ACH return.
tags:
- chargeBacks
parameters:
- name: Id
in: path
description: ID of the chargeback or return record.
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
- 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/AddResponseResponse'
'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/ResponseChargeBack'
/ChargeBacks/getChargebackAttachments/{Id}/{fileName}:
get:
operationId: getChargebackAttachment
summary: Get ChargeBack attachment by fileName
description: Retrieves a chargeback attachment file by its file name.
tags:
- chargeBacks
parameters:
- name: fileName
in: path
description: The chargeback attachment's file name.
required: true
schema:
type: string
- name: Id
in: path
description: The ID of chargeback or return record.
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: OK
content:
application/json:
schema:
type: string
'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:
AccountId:
type: string
description: Custom identifier for payment connector.
title: AccountId
Shippingaddress:
type: string
description: The shipping address.
title: Shippingaddress
AvsResponse:
type: string
description: 'Text code describing the result for address validation (applies only for
card transactions).
'
title: AvsResponse
FreightAmount:
type: number
format: double
description: Freight/shipping amount.
title: FreightAmount
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
ResponseChargeBack:
type: object
properties:
attachments:
$ref: '#/components/schemas/Attachments'
description: Array of attached files to response.
contactEmail:
$ref: '#/components/schemas/Email'
description: Email of response submitter.
contactName:
type: string
description: Name of response submitter
notes:
type: string
description: Response notes
title: ResponseChargeBack
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
CvvResponseText:
type: string
description: 'Text code describing the result for CVV validation (applies only for card
transactions).
'
title: CvvResponseText
BillDataPaymentTerms:
type: string
enum:
- PIA
- CIA
- UR
- NET10
- NET20
- NET30
- NET45
- NET60
- NET90
- EOM
- MFI
- 5MFI
- 10MFI
- 15MFI
- 20MFI
- 2/10NET30
- UF
- 10UF
- 20UF
- 25UF
- 50UF
description: 'Payment terms for invoice. If no terms are defined, then response data for
this field defaults to `NET30`. Mirrors the values in
[`Terms`](#schema-terms).
'
title: BillDataPaymentTerms
Email:
type: string
format: email
description: Email address.
title: Email
Accountexp:
type: string
description: Expiration date of card used in transaction.
title: Accountexp
SplitCount:
type: integer
description: 'Number of split funding instructions associated with the transaction.
Returns `0` when the transaction has no splits.
'
title: SplitCount
CvvResponse:
type: string
description: 'Text code describing the result for CVV validation (applies only for card
transactions).
'
title: CvvResponse
ResultCodeText:
type: string
description: 'Description of the result code. See
[Pay In unified response codes](/guides/pay-in-unified-response-codes-reference)
for more information.
'
title: ResultCodeText
Discount:
type: number
format: double
description: Discount applied to the invoice.
title: Discount
CustomerStatus:
type: integer
description: 'Customer Status. Possible values:
- `-99` Deleted
- `0` Inactive
- `1` Active
- `85` Locked (typically due to multiple failed login attempts)
'
title: CustomerStatus
ItemUnitofMeasure:
type: string
description: Unit of measurement. Max length of 100 characters.
title: ItemUnitofMeasure
SummaryCommodityCode:
type: string
description: Commodity code.
title: SummaryCommodityCode
TransactionTime:
type: string
format: date-time
description: Timestamp when transaction was submitted, in UTC.
title: TransactionTime
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
PageIdentifier:
type: string
description: Auxiliary validation used internally by payment pages and components.
title: PageIdentifier
QueryTransactionPayorData:
type: object
properties:
Identifiers:
type: array
items:
description: Any type
description: Array of field names to be used as identifiers.
FirstName:
type: string
description: Customer/Payor first name.
LastName:
type: string
description: Customer/Payor last name.
CompanyName:
type: string
description: Customer's company name.
BillingAddress1:
type: string
description: Customer's billing address.
BillingAddress2:
type: string
description: Additional line for Customer's billing address.
BillingCity:
type: string
description: Customer's billing city.
BillingState:
type: string
description: Customer's billing state. Must be 2-letter state code for address in US.
BillingZip:
$ref: '#/components/schemas/BillingZip'
description: Customer's billing ZIP code.
BillingCountry:
type: string
description: Customer's billing country.
BillingPhone:
type: string
description: Customer's phone number.
BillingEmail:
$ref: '#/components/schemas/Email'
description: Customer's email address.
CustomerNumber:
$ref: '#/components/schemas/CustomerNumberNullable'
ShippingAddress1:
$ref: '#/components/schemas/Shippingaddress'
ShippingAddress2:
$ref: '#/components/schemas/Shippingaddressadditional'
ShippingCity:
$ref: '#/components/schemas/Shippingcity'
ShippingState:
$ref: '#/components/schemas/Shippingstate'
ShippingZip:
$ref: '#/components/schemas/Shippingzip'
ShippingCountry:
$ref: '#/components/schemas/Shippingcountry'
customerId:
$ref: '#/components/schemas/CustomerId'
customerStatus:
$ref: '#/components/schemas/CustomerStatus'
AdditionalData:
$ref: '#/components/schemas/AdditionalDataMap'
title: QueryTransactionPayorData
DutyAmount:
type: number
format: double
description: Duty amount.
title: DutyAmount
Tax:
type: number
format: double
description: Tax rate in percent applied to the invoice.
title: Tax
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
ItemDescription:
type: string
description: Item or product description. Max length of 250 characters.
title: ItemDescription
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
AchHolderType:
type: string
enum:
- personal
- business
default: personal
description: 'The bank''s accountholder type: personal or business.
'
title: AchHolderType
Shippingstate:
type: string
description: Shipping state or province.
title: Shippingstate
Initiator:
type: string
description: 'The transaction''s initiator. Indicates who initiated the transaction.
'
title: Initiator
FeeAmount:
type: number
format: double
description: Service fee or sub-charge applied.
title: FeeAmount
CustomerId:
type: integer
format: int64
description: The Payabli-generated unique ID for the customer.
title: CustomerId
ExternalProcessorInformation:
type: string
description: Information from the external processor about the transaction.
title: ExternalProcessorInformation
CustomerNumberNullable:
type: string
description: 'User-provided unique identifier for the customer. This is typically the
customer ID from your own system.
'
title: CustomerNumberNullable
BillItem:
type: object
properties:
itemCategories:
type: array
items:
type: string
description: Array of tags classifying item or product.
itemCommodityCode:
$ref: '#/components/schemas/ItemCommodityCode'
itemCost:
type: number
format: double
description: Item or product price per unit.
itemDescription:
$ref: '#/components/schemas/ItemDescription'
itemMode:
type: integer
description: 'Internal class of item or product: value `0` is only for invoices,
`1` for bills, and `2` is common for both. Required on invoice line
items — invoice creation fails with `Invalid item data` if it''s omitted.
'
itemProductCode:
$ref: '#/components/schemas/ItemProductCode'
itemProductName:
$ref: '#/components/schemas/ItemProductName'
itemQty:
type: integer
description: Quantity of item or product.
itemTaxAmount:
type: number
format: double
description: Tax amount applied to item or product.
itemTaxRate:
type: number
format: double
description: Tax rate applied to item or product.
itemTotalAmount:
type: number
format: double
description: 'Per-line total for this item (unit cost times quantity). Distinct from
the invoice''s overall total, `invoiceAmount`. Required on invoice line items.
'
itemUnitOfMeasure:
$ref: '#/components/schemas/ItemUnitofMeasure'
title: BillItem
ItemProductCode:
type: string
description: Item or product code. Max length of 250 characters.
title: ItemProductCode
TransactionQueryRecords:
type: object
properties:
AchHolderType:
$ref: '#/components/schemas/AchHolderType'
default: personal
AchSecCode:
$ref: '#/components/schemas/AchSecCode'
BatchAmount:
type: number
format: double
description: Batch amount.
BatchNumber:
$ref: '#/components/schemas/BatchNumber'
CfeeTransactions:
type: array
items:
$ref: '#/components/schemas/QueryCFeeTransaction'
description: Service Fee or sub-charge transaction associated to the main transaction.
ConnectorName:
type: string
description: Connector used for transaction.
Customer:
$ref: '#/components/schemas/QueryTransactionPayorData'
DeviceId:
$ref: '#/components/schemas/Device'
EntrypageId:
$ref: '#/components/schemas/EntrypageId'
ExternalProcessorInformation:
$ref: '#/components/schemas/ExternalProcessorInformation'
FeeAmount:
$ref: '#/components/schemas/FeeAmount'
GatewayTransId:
type: string
description: Internal identifier used for processing.
invoiceData:
$ref: '#/components/schemas/BillData'
Method:
type: string
description: 'Payment method used: card, ach, or wallet.'
NetAmount:
$ref: '#/components/schemas/Netamountnullable'
description: Net amount paid.
Operation:
$ref: '#/components/schemas/Operation'
OrderId:
$ref: '#/components/schemas/OrderId'
OrgId:
$ref: '#/components/schemas/Orgid'
description: ID of immediate parent organization.
ParentOrgName:
$ref: '#/components/schemas/OrgParentName'
PaymentData:
$ref: '#/components/schemas/QueryPaymentData'
PaymentTransId:
type: string
description: Unique Transaction ID.
PayorId:
$ref: '#/components/schemas/PayorId'
PaypointDbaname:
$ref: '#/components/schemas/Dbaname'
description: Paypoint's DBA name.
PaypointEntryname:
$ref: '#/components/schemas/Entrypointfield'
description: Paypoint's entryname.
PaypointId:
type: integer
format: int64
description: InternalId for paypoint.
PaypointLegalname:
$ref: '#/components/schemas/Legalname'
description: Paypoint's legal name.
PendingFeeAmount:
$ref: '#/components/schemas/PendingFeeAmount'
RefundId:
$ref: '#/components/schemas/RefundId'
ResponseData:
$ref: '#/components/schemas/QueryResponseData'
ReturnedId:
$ref: '#/components/schemas/ReturnedId'
ScheduleReference:
type: integer
format: int64
description: Reference to the subscription that originated the transaction.
SettlementStatus:
type: integer
description: Settlement status for transaction. See [the docs](/developers/references/money-in-statuses#payment-funding-status) for a full reference.
Source:
$ref: '#/components/schemas/Source'
splitFundingInstructions:
$ref: '#/components/schemas/SplitFunding'
splitCount:
$ref: '#/components/schemas/SplitCount'
TotalAmount:
type: number
format: double
description: Transaction total amount (including service fee or sub-charge)
TransactionEvents:
type: array
items:
$ref: '#/components/schemas/QueryTransactionEvents'
description: Events associated with this transaction.
TransactionTime:
type:
- string
- 'null'
format: date-time
description: Transaction date and time, in UTC.
TransAdditionalData:
description: Any type
TransStatus:
type: integer
description: Status of transaction. See [the docs](/developers/references/money-in-statuses#money-in-transaction-status) for a full reference.
required:
- splitCount
- TransactionTime
title: TransactionQueryRecords
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
BillData:
type: object
properties:
AdditionalData:
$ref: '#/components/schemas/AdditionalDataMap'
attachments:
$ref: '#/components/schemas/Attachments'
company:
type: string
description: Company name of the recipient of the invoice.
discount:
$ref: '#/components/schemas/Discount'
dutyAmount:
$ref: '#/components/schemas/DutyAmount'
firstName:
type: string
description: First name of the recipient of the invoice.
freightAmount:
$ref: '#/components/schemas/FreightAmount'
frequency:
$ref: '#/components/schemas/Frequency'
description: Frequency of scheduled invoice.
invoiceAmount:
$ref: '#/components/schemas/InvoiceAmount'
invoiceDate:
type: string
format: date
description: 'Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.'
invoiceDueDate:
type: string
format: date
description: 'Invoice due date in one of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.'
invoiceEndDate:
type: string
format: date
description: 'Indicate the date to finish a scheduled invoice cycle (`invoiceType`` = 1) in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.'
invoiceNumber:
$ref: '#/components/schemas/InvoiceNumber'
description: Invoice number. Identifies the invoice under a paypoint.
invoiceStatus:
$ref: '#/components/schemas/Invoicestatus'
invoiceType:
$ref: '#/components/schemas/InvoiceType'
items:
type: array
items:
$ref: '#/components/schemas/BillItem'
description: Array of line items included in the invoice.
lastName:
type: string
description: Last name of the recipient of the invoice.
notes:
type: string
description: Notes included in the invoice.
paymentTerms:
$ref: '#/components/schemas/BillDataPaymentTerms'
purchaseOrder:
$ref: '#/components/schemas/PurchaseOrder'
shippingAddress1:
$ref: '#/components/schemas/Shippingaddress'
shippingAddress2:
$ref: '#/components/schemas/Shippingaddressadditional'
shippingCity:
$ref: '#/components/schemas/Shippingcity'
shippingCountry:
$ref: '#/components/schemas/Shippingcountry'
shippingEmail:
$ref: '#/components/schemas/Email'
description: Shipping recipient's contact email address.
shippingFromZip:
$ref: '#/components/schemas/ShippingFromZip'
shippingPhone:
type: string
description: Recipient phone number.
shippingState:
$ref: '#/components/schemas/Shippingstate'
shippingZip:
$ref: '#/components/schemas/Shippingzip'
summaryCommodityCode:
$ref: '#/components/schemas/SummaryCommodityCode'
tax:
$ref: '#/components/schemas/Tax'
termsConditions:
$ref: '#/components/schemas/TermsConditions'
title: BillData
AddResponseResponse:
type: object
properties:
isSuccess:
$ref: '#/components/schemas/IsSuccess'
responseText:
$ref: '#/components/schemas/ResponseText'
responseData:
type: integer
description: 'If `isSuccess` = true, this contains the chargeback identifier. If
`isSuccess` = false, this contains the reason for the error.
'
required:
- responseText
description: 'Minimal response wrapper used by approval-style endpoints that don''t carry
the standard response envelope.
'
title: AddResponseResponse
IsSuccess:
type: boolean
description: 'Boolean indicating whether the operation was successful. A `true` value
indicates success. A `false` value indicates failure.
'
title: IsSuccess
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
Shippingcountry:
type: string
description: Shipping address country.
title: Shippingcountry
BatchNumber:
type: string
description: 'A unique identifier for the batch. This is generated by Payabli when the
batch is created, and follows this format:
`paypointId + "_" + serviceName + "_" + batchDate:yyyyMMdd + "_" + Guid.NewGuid()`.
Payabli generates the GUID to ensure that the batch number is unique.
For example, in this batch number:
`123_card_20251008_3f2504e0-4f89-11d3-9a0c-0305e82c3301`, the paypointID
is `123`, the service is `card`, the batch date is `2025-10-08`, and
the GUID is `3f2504e0-4f89-11d3-9a0c-0305e82c3301`.
'
title: BatchNumber
Device:
type: string
description: Identifier of registered cloud device used in the transaction.
title: Device
PendingFeeAmount:
type: number
format: double
description: 'The difference between the configured pass-through fee and the fee amount
sent in the request. When transferring funds, Payabli uses this field to
deduct the fee difference and transfer the correct amount to the
merchant.
When a paypoint is set up to absorb fees, and th
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/payabli/refs/heads/main/openapi/payabli-chargebacks-api-openapi.yml