Payabli chargeBacks API
The chargeBacks API from Payabli — 3 operation(s) for chargebacks.
The chargeBacks API from Payabli — 3 operation(s) for chargebacks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/payabli-chargebacks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: reference Charge Backs 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:
ItemDescription:
type: string
description: Item or product description. Max length of 250 characters.
title: ItemDescription
SplitFundingContent:
type: object
properties:
accountId:
type: string
description: The accountId for the account the split should be sent to.
amount:
type: number
format: double
description: Amount from the transaction to send to this recipient.
description:
type: string
description: A description for the split.
recipientEntryPoint:
type: string
description: The entrypoint the split should be sent to.
title: SplitFundingContent
AvsResponseText:
type: string
description: 'Text code describing the result for address validation (applies only for
card transactions).
'
title: AvsResponseText
ExternalPaypointId:
type: string
description: 'A custom identifier for the paypoint, if applicable.
'
title: ExternalPaypointId
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
SummaryCommodityCode:
type: string
description: Commodity code.
title: SummaryCommodityCode
QueryTransactionEventsEventData:
oneOf:
- type: object
additionalProperties:
description: Any type
- type: string
description: 'Any data associated to the event received from processor. Contents vary
by event type.
'
title: QueryTransactionEventsEventData
Sequence:
type: string
description: "The order of the transaction for cardholder-initiated transaction (CIT)\nand merchant-initiated transaction (MIT) purposes. This field is\nautomatically detected and populated by Payabli.\n\nAvailable values:\n\n- `first`: The first use of the payment method. This is almost always\n a cardholder-initiated transaction.\n- `subsequent`: For merchant-initiated transactions after the first use\n of the payment method.\n\nSee\n[Understanding CIT and MIT Indicators](/guides/pay-in-transactions-cit-mit-overview)\nfor more information.\n"
title: Sequence
PaymentCategories:
type: object
properties:
amount:
type: number
format: double
description: Price/cost per unit of item or category.
description:
type: string
description: Description of item or category
label:
type: string
description: Name of item or category.
qty:
type: integer
default: 1
description: Quantity of item or category
required:
- amount
- label
title: PaymentCategories
IsSuccess:
type: boolean
description: 'Boolean indicating whether the operation was successful. A `true` value
indicates success. A `false` value indicates failure.
'
title: IsSuccess
FeeAmount:
type: number
format: double
description: Service fee or sub-charge applied.
title: FeeAmount
Storedmethodid:
type: string
description: 'Payabli identifier of a tokenized payment method. If this field is
used in a request, the `method` field is overridden and the payment
is made using the payment token.
'
title: Storedmethodid
PayorId:
type: integer
format: int64
description: 'Unique ID for the customer linked to the transaction. This is the same
value as the `customerId` used when creating or referencing a customer.
'
title: PayorId
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
FileContentFtype:
type: string
enum:
- pdf
- doc
- docx
- jpg
- jpeg
- png
- gif
- txt
description: The MIME type of the file (if content is provided).
title: FileContentFtype
ChargebackQueryRecords:
type: object
properties:
Id:
type: integer
format: int64
description: Identifier of chargeback or return.
ChargebackDate:
type: string
format: date-time
description: Date of chargeback in format YYYY-MM-DD or MM/DD/YYYY.
CaseNumber:
type: string
description: Number of case assigned to the chargeback.
ReasonCode:
type: string
description: R code for returned ACH or custom code identifying the reason.
Reason:
type: string
description: Text describing the chargeback or ACH return reason.
ReferenceNumber:
type: string
description: Processor reference number to the chargeback.
LastFour:
type: string
description: Last 4 digits of card or bank account involved in chargeback or return.
AccountType:
$ref: '#/components/schemas/Accounttype'
Status:
type: integer
description: 'Status for chargeback or ACH return
- 0: Open (chargebacks only)
- 1: Pending (chargebacks only)
- 2: Closed-Won (chargebacks only)
- 3: Closed-Lost (chargebacks only)
- 4: ACH Return (ACH only)
- 5: ACH Dispute, Not Authorized (ACH only)'
Method:
type: string
description: 'Type of payment vehicle: **ach** or **card**.'
CreatedAt:
$ref: '#/components/schemas/CreatedAt'
description: Timestamp when the register was created, in UTC.
ReplyBy:
$ref: '#/components/schemas/Replyby'
PaymentTransId:
type: string
description: ReferenceId of the transaction in Payabli.
ScheduleReference:
type: integer
format: int64
description: Reference to the subscription originating the transaction.
OrderId:
$ref: '#/components/schemas/OrderId'
NetAmount:
$ref: '#/components/schemas/Netamountnullable'
description: Net amount in chargeback or ACH return.
TransactionTime:
$ref: '#/components/schemas/TransactionTime'
Customer:
$ref: '#/components/schemas/QueryTransactionPayorData'
PaymentData:
$ref: '#/components/schemas/QueryPaymentData'
PaypointLegalname:
$ref: '#/components/schemas/Legalname'
description: The paypoint's legal name.
PaypointDbaname:
$ref: '#/components/schemas/Dbaname'
description: The paypoint's DBA name.
ParentOrgName:
$ref: '#/components/schemas/OrgParentName'
ParentOrgId:
type: integer
format: int64
description: The ID of the parent organization.
PaypointEntryname:
$ref: '#/components/schemas/Entrypointfield'
description: The paypoint's entryname.
Responses:
type: array
items:
$ref: '#/components/schemas/ChargeBackResponse'
description: Chargeback response records.
Transaction:
$ref: '#/components/schemas/TransactionQueryRecords'
externalPaypointID:
$ref: '#/components/schemas/ExternalPaypointId'
pageidentifier:
$ref: '#/components/schemas/PageIdentifier'
messages:
type: array
items:
$ref: '#/components/schemas/ChargebackMessage'
description: Messages related to the chargeback.
ServiceGroup:
type: string
description: Service group classification.
DisputeType:
type: string
description: Type of dispute classification.
ProcessorName:
type: string
description: Name of the payment processor.
required:
- Id
- ChargebackDate
- CaseNumber
- ReasonCode
- Reason
- ReferenceNumber
- LastFour
- AccountType
- Status
- Method
- CreatedAt
- ReplyBy
- PaymentTransId
- OrderId
- TransactionTime
- Customer
- PaymentData
- PaypointLegalname
- PaypointDbaname
- ParentOrgName
- ParentOrgId
- PaypointEntryname
- Responses
- Transaction
- messages
- ServiceGroup
- DisputeType
- ProcessorName
title: ChargebackQueryRecords
AdditionalDataMap:
type: object
additionalProperties:
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. If you are using\n[custom identifiers](/developers/developer-guides/entities-customers),\npass those in this object. Max length for a value is 100 characters.\n\n```json\n{\n \"additionalData\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\",\n \"key3\": \"value3\"\n }\n}\n```\n"
title: AdditionalDataMap
SplitFunding:
type: array
items:
$ref: '#/components/schemas/SplitFundingContent'
description: Split funding instructions for the transaction. The total amount of the splits must match the total amount of the transaction.
title: SplitFunding
Orgid:
type: integer
format: int64
description: Organization ID. Unique identifier assigned to an org by Payabli.
title: Orgid
Operation:
type: string
description: The transaction's operation.
title: Operation
InvoiceAmount:
type: number
format: double
description: The invoice amount.
title: InvoiceAmount
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
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
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
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
Orderdescription:
type: string
description: Text description of the transaction.
title: Orderdescription
Accounttype:
type: string
description: Bank account type or card brand.
title: Accounttype
AchHolderType:
type: string
enum:
- personal
- business
default: personal
description: 'The bank''s accountholder type: personal or business.
'
title: AchHolderType
ItemProductName:
type: string
description: Item or product name. Max length of 250 characters.
title: ItemProductName
OrderId:
type: string
description: Custom identifier for the transaction.
title: OrderId
TermsConditions:
type: string
description: Custom terms and conditions included in the invoice.
title: TermsConditions
ExternalProcessorInformation:
type: string
description: Information from the external processor about the transaction.
title: ExternalProcessorInformation
Attachments:
type: array
items:
$ref: '#/components/schemas/FileContent'
description: 'Array of `fileContent` objects with attached documents. Max upload size is
30 MB.
'
title: Attachments
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 the pass-through fee sent
with the request is less than the configured amount, the difference must
be covered by the merchant. See
[Fee Configuration](/guides/pay-in-fees-passthrough-overview#fee-configuration)
to learn more about pass-through fee settings.
'
title: PendingFeeAmount
CustomerNumberNullable:
type: string
description: 'User-provided unique identifier for the customer. This is typically the
customer ID from your own system.
'
title: CustomerNumberNullable
ResultCodev2:
type: string
description: 'Unified result code for the transaction. See
[Pay In unified response codes](/guides/pay-in-unified-response-codes-reference)
for more information.
'
title: ResultCodev2
Entrypointfield:
type: string
description: The entrypoint identifier.
title: Entrypointfield
AccountId:
type: string
description: Custom identifier for payment connector.
title: AccountId
Invoicestatus:
type: integer
description: Invoice status code.
title: Invoicestatus
Shippingcountry:
type: string
description: Shipping address country.
title: Shippingcountry
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
InvoiceType:
type: integer
description: 'Invoice type. Value `0` is for single/one-time invoices, `1` for
scheduled invoices.
'
title: InvoiceType
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
Source:
type: string
description: Custom identifier to indicate the transaction or request source.
title: Source
ShippingFromZip:
type: string
description: Sender shipping ZIP code.
title: ShippingFromZip
CustomerId:
type: integer
format: int64
description: The Payabli-generated unique ID for the customer.
title: CustomerId
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
Discount:
type: number
format: double
description: Discount applied to the invoice.
title: Discount
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
Shippingaddress:
type: string
description: The shipping address.
title: Shippingaddress
Legalname:
type: string
description: Business legal name.
title: Legalname
PaymentDetail:
type: object
properties:
categories:
type: array
items:
$ref: '#/components/schemas/PaymentCategories'
description: 'Array of payment categories/line items describing the amount to be paid.
**Note**: These categories are for information only and aren''t validated against the total amount provided.'
checkImage:
type: object
additionalProperties:
description: Any type
description: Object containing image of paper check.
checkNumber:
type: string
description: A check number to be used in the ach transaction. **Required** for payment method = 'check'.
currency:
type: string
description: The currency for the transaction, `USD` or `CAD`. If your paypoint is configured for CAD, you must send the `CAD` value in this field, otherwise it defaults to USD, which will cause the transaction to fail.
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. If you are using a percentage-based fee schedule, you must calculate the value manually.
splitFunding:
$ref: '#/components/schemas/SplitFunding'
description: Split funding instructions for the transaction. See [Split a Transaction](/developers/developer-guides/money-in-split-funding) for more.
checkUniqueId:
type: string
description: Unique identifier for a processed check image. Required for RDC (Remote Deposit Capture) transactions where `achCode` is `BOC`. Use the `id` value from the [check processing](/developers/api-reference/moneyin/check-capture) response.
totalAmount:
type: number
format: double
description: Total amount to be charged. If a service fee is sent, then this amount should include the service fee."
required:
- totalAmount
description: Details about the payment.
title: PaymentDetail
BillingZip:
type: string
description: Billing address ZIP code.
title: BillingZip
ItemProductCode:
type: string
description: Item or product code. Max length of 250 characters.
title: ItemProductCode
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
AvsResponse:
type: string
description: 'Text code describing the result for address validation (applies only for
card transactions).
'
title: AvsResponse
Shippingstate:
type: string
description: Shipping state or province.
title: Shippingstate
QueryCFeeTransaction:
type: object
properties:
cFeeTransid:
type: string
feeAmount:
type: number
format: double
operation:
type: string
refundId:
type: integer
format: int64
responseData:
type: object
additionalProperties:
description: Any type
settlementStatus:
type: integer
transactionTime:
$ref: '#/components/schemas/TransactionTime'
transStatus:
type: integer
title: QueryCFeeTransaction
ReturnedId:
type: integer
format: int64
description: Identifier of return/chargeback transaction linked to this payment.
title: ReturnedId
QueryTransactionEvents:
type: object
properties:
TransEvent:
type: string
description: Event descriptor. See [TransEvent Reference](/guides/pay-in-transevents-reference) for more details.
EventData:
$ref: '#/components/schemas/QueryTransactionEventsEventData'
description: Any data associated to the event received from processor. Contents vary by event type.
EventTime:
type: string
format: date-time
description: Date and time of event.
title: QueryTransactionEvents
EmvAuthResponseData:
type: string
description: EMV authorization response data, applicable for card transactions.
title: EmvAuthResponseData
PurchaseOrder:
type: string
description: Purchase order number.
title: PurchaseOrder
Tax:
type: number
format: double
description: Tax rate in percent applied to the invoice.
title: Tax
CvvResponseText:
type: string
description: 'Text code describing the result for CVV validation (applies only for card
transactions).
'
title: CvvResponseText
ChargebackMessage:
type: object
properties:
Id:
type: integer
description: Message identifier.
RoomId:
type: integer
description: Room identifier for the message.
UserId:
type: integer
description: User identifier who sent the message.
UserName:
type: string
# --- 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