laratusk/chargebacks911

ChargeBack 911 integration for Laravel

Maintainers

Package info

github.com/laratusk/chargebacks911

pkg:composer/laratusk/chargebacks911

Statistics

Installs: 76

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

1.0.0 2026-02-27 14:10 UTC

Requires

Requires (Dev)

MIT 1d213242148670315e3132dee947b4b27c14c56e

  • Azer Mammedov <mamedovazer124.woop@gmail.com>

This package is auto-updated.

Last update: 2026-02-27 20:48:25 UTC

README

https://apidoc.chargebacks911.com/documentation

Installation

composer require laratusk/chargebacks911

Publish the config file:

php artisan vendor:publish --tag=chargeback-config

Add the following to your .env:

CHARGEBACK_ENABLED=true
CHARGEBACK_URL=https://api.chargebacks911.com/v2
CHARGEBACK_USERNAME=your-username
CHARGEBACK_PASSWORD=your-password

Usage

Merchant Info

use Laratusk\Chargebacks911\ChargeBack;

// Get full merchant payload
$merchant = ChargeBack::merchant();

// Get a specific field
$merchantId = ChargeBack::merchant('id');

Orders

List orders

$orders = ChargeBack::orders()->list();

// With filters
$orders = ChargeBack::orders()->list(params: [
    'start_date' => '2024-01-01',
    'end_date'   => '2024-12-31',
]);

Add an order

use Laratusk\Chargebacks911\ChargeBack;
use Laratusk\Chargebacks911\Generics\Order;
use Laratusk\Chargebacks911\Generics\Transaction;
use Laratusk\Chargebacks911\Generics\Billing;
use Laratusk\Chargebacks911\Generics\Address;
use Laratusk\Chargebacks911\Generics\Card;

$transaction = new Transaction([
    'id'                 => 'TXN-001',
    'mid'                => '21226255',
    'settlement_amount'  => '99.99',
    'settlement_date'    => '2024-06-01',
    'status'             => 'Approved',
    'card'               => new Card([
        'type'      => 'Visa',
        'number'    => '411111xxxxxx1111',
        'exp_month' => '12',
        'exp_year'  => '2026',
    ]),
]);

$order = new Order([
    'id'             => 'ORD-001',
    'date'           => '2024-06-01',
    'total_amount'   => 99.99,
    'total_currency' => 'USD',
    'transactions'   => [$transaction],
    'billing'        => new Billing([
        'contact_first_name' => 'Jane',
        'contact_last_name'  => 'Doe',
        'email'              => 'jane@example.com',
        'address'            => new Address([
            'street'   => '123 Main St',
            'city'     => 'Tampa',
            'state'    => 'FL',
            'postcode' => '33601',
            'country'  => 'US',
        ]),
    ]),
]);

$uid = ChargeBack::orders()->add($order);

Update an order (PUT — full replace)

ChargeBack::orders()->updatePut($order);

Update an order (PATCH — partial update)

$uid = ChargeBack::orders()->updatePatch($order, 'existing-uid');

Chargebacks

List chargebacks

$chargebacks = ChargeBack::chargebacks()->list();

// With filters (paginated, max 2500 per page)
$chargebacks = ChargeBack::chargebacks()->list([
    'start_date' => '2024-01-01',
    'end_date'   => '2024-12-31',
    'status'     => 'new',
    'page'       => 1,
]);

foreach ($chargebacks as $chargeback) {
    echo $chargeback->case_no;
    echo $chargeback->status;
    echo $chargeback->dispute_amount;
}

// Paginate until no records remain
$page = 1;
do {
    $results = ChargeBack::chargebacks()->list(['page' => $page++]);
} while ($results->isNotEmpty());

Alerts

List alerts

$alerts = ChargeBack::alerts()->list();

// With filters
$alerts = ChargeBack::alerts()->list([
    'date_start' => '2024-01-01',
    'date_end'   => '2024-12-31',
    'type'       => 'vmpi',
    'completed'  => 0,
    'page'       => 1,
]);

foreach ($alerts as $alert) {
    echo $alert->id;
    echo $alert->amount;
    echo $alert->type;
}

Update an alert

use Laratusk\Chargebacks911\Generics\AlertUpdate;

$update = new AlertUpdate([
    'outcome_id'    => 3,           // required
    'order_id'      => 'ORD-001',
    'refund_amount' => 99.99,
]);

$result = ChargeBack::alerts()->update('alert-id-123', $update);

Alert Outcomes

$outcomes = ChargeBack::alertOutcomes()->list();

// With filters
$outcomes = ChargeBack::alertOutcomes()->list([
    'is_refund' => true,
    'is_valid'  => true,
]);

Webhooks

List webhooks

$webhooks = ChargeBack::webhooks()->list();

Show a single webhook

$webhook = ChargeBack::webhooks()->show('webhook-id-123');

Register a webhook

use Laratusk\Chargebacks911\Enums\Event;

$webhook = ChargeBack::webhooks()->add(
    Event::CASE_CREATED,
    'https://your-app.example.com/webhooks/chargebacks'
);

Available events:

Constant Value
Event::ALERT_CREATED ALERT_CREATED
Event::ALERT_STATUS_CHANGED ALERT_STATUS_CHANGED
Event::CASE_CREATED CASE_CREATED
Event::CASE_STATUS_CHANGED CASE_STATUS_CHANGED
Event::CASE_VERDICT_CHANGED CASE_VERDICT_CHANGED
Event::DOC_VALIDATION_ERROR DOC_VALIDATION_ERROR
Event::ERT_CREATED ERT_CREATED
Event::ERT_RESOLVED ERT_RESOLVED

Update a webhook endpoint

$webhook = ChargeBack::webhooks()->update('webhook-id-123', 'https://your-app.example.com/new-endpoint');

Delete a webhook

ChargeBack::webhooks()->delete('webhook-id-123');

Send a test event

ChargeBack::webhooks()->test('webhook-id-123');

Exception Handling

use Laratusk\Chargebacks911\Exceptions\AuthenticationException;
use Laratusk\Chargebacks911\Exceptions\NotFoundException;
use Laratusk\Chargebacks911\Exceptions\RateLimitException;
use Laratusk\Chargebacks911\Exceptions\ApiException;

try {
    $chargebacks = ChargeBack::chargebacks()->list();
} catch (AuthenticationException $e) {
    // 401 — invalid credentials
} catch (NotFoundException $e) {
    // 404 — resource not found
} catch (RateLimitException $e) {
    // 429 — too many requests
} catch (ApiException $e) {
    // other API errors
}

Add Orders

This allows the merchant to upload orders into our platform. The structured JSON schema in the request body ensures clarity and precision in conveying essential order details while allowing flexibility in what data elements are conveyed to our platform. Users can efficiently contribute new order information to enhance the platform's transactional insights

Please note that the payload received under the meta optional property would be saved for data enrichment. POST /orders endpoint's response for the meta property would be limited compared to what is received in POST request.

Field Details
merchantId required
Type integer
Description The Defined ID value associated with the Merchant

Fields

Field Details
acquire_date Type: string
Description: Date of customer's account creation
affiliate_id Type: string
Description: Affiliate, store or franchisee ID
affiliate_name Type: string
Description: Affiliate, store or franchisee ID
billing Type: object
Description: An object containing order billing details
campaign_id Type: integer
Description: ID of the order's campaign
child_order_id Type: string
Description: The merchant’s custom unique child order identifier of the order id, from their CRM/OMS
coupon_discount Type: object
Description: Coupon/Discount amount deducted from the order
date Type: string
Description: Date that the order was processed in the merchant’s CRM/OMS
date_of_last_contact Type: string
Description: The most recent date that the customer was contacted
employee_name Type: string
Description: Merchant employee’s name who created the order in the CRM/OMS
employee_username Type: string
Description: Merchant employee’s username who created the order in the CRM/OMS
hold_date Type: string
Description: Date when customer’s recurring orders stopped or put this order on hold
id Type: string
Description: ID of the transaction
Required: Yes
is_blacklisted Type: boolean
Description: Is the customer blacklisted in the CRM/OMS? (true/false)
is_fraud Type: boolean
Description: Is this order flagged as fraud in the CRM/OMS? (true/false)
meta Type: object
Description: An object containing customer identification, social media, historical purchases, and order-related screenshots
on_hold_by Type: string
Description: The username of the merchant’s agent who placed the order on hold
order_click_id Type: string
Description: To track the online traffic source reference identifier
order_contact_email Type: string
Description: Customer’s email address. Note: Required if the order source is PayPal.
order_contact_phone Type: string
Description: Customer’s phone number
order_notes Type: Array of strings
Description: An array of notes related to this order
parent_order_id Type: string
Description: The merchant’s custom unique parent order identifier of the order id, from their CRM/OMS
publisher_id Type: string
Description: Publisher or promoter identifier
publisher_name Type: string
Description: Publisher or promoter name
sales_tax_amount Type: string
Description: Order sales tax amount
sales_tax_percent Type: string
Description: Order sales tax percent
shipping_charge Type: string
Description: Shipping charge amount
status_confirmation Type: string
Description: Order has received confirmation in the merchant’s CRM/OMS and sent to Fulfillment for processing
status_confirmation_date Type: string
Description: Date when the order was confirmed and sent to Fulfillment
store_location Type: string
Description: A link to the merchant’s website or physical store identifier
sub_affiliate_id Type: string
Description: Affiliate, store or franchisee subdivision identifier
sub_affiliate_name Type: string
Description: Affiliate, store or franchisee subdivision name
total_amount Type: number
Description: Order amount total
total_currency Type: string
Description: The currency type of the order total
transactions Type: Array of objects
Description: An array of transactions objects related to the order. Note: For Getting Orders, the transactions value will be an object containing the first transaction posted (not an array of objects)
Required: Yes
travel_and_entertainment Type: object
Description: (No description provided)
voice_signature Type: string
Description: A link pointing to a file containing a recording of the audio at the time of order (Phone Orders)

Billing Object

Field Details
address Type: object
Description: Billing address details
company Type: string
Description: Billing company
contact_first_name Type: string
Description: Billing contact first name
contact_last_name Type: string
Description: Billing contact last name
email Type: string
Description: Billing email
fax Type: string
Description: Billing fax number
phone Type: string
Description: Billing phone number

Address Object (Billing)

Field Details
city Type: string
Description: Billing City
country Type: string
Description: Billing Country
postcode Type: string
Description: Billing Postcode
state Type: string
Description: Billing region or state
street Type: string
Description: Billing Address
street_2 Type: string
Description: Billing address (second line)

Meta Object

Field Details
customer Type: object
Description: Customer details
screenshots Type: object
Description: (No description provided)

Customer Object (Meta)

Field Details
date_of_first_transaction Type: string
Description: Date of the customer's first transaction.
dob Type: string
Description: Customer's date of birth (yyyy-mm-dd)
drivers_license_number Type: string
Description: Customer's driver's license number (for electronic check/debit card).
history Type: Array of objects
Description: An array of historic transactions and profile updates related to this customer (preferred going back the last 6 months). Note: For Getting Orders, the history value will be an object containing the first customer history object submitted (not an array of objects).
id Type: integer
Description: Customer ID.
passport_number Type: integer
Description: Customer's passport number
profile_updates Type: Array of strings
Description: An array of customer's profile updates. Example: {'new payment method added', 'customer updated primary email address'}
refund_total Type: string
Description: The total amount refunded to the customer so far on this order.
social_media Type: object
Description: An object containing social media information related to this customer
ssn Type: string
Description: The customers SSN (Social Security Number) (for debit card purchases).
type Type: string
Description: Customer type in the CRM/OMS

Social Media Object (Customer)

Field Details
url Type: string
Description: Customer's Social URL
username Type: string
Description: Customer's social media username

History Object (Customer)

Field Details
arn Type: string
Description: Acquirer Reference Number
auth_id Type: string
Description: Authorization code at the time of the transaction
auth_type Type: string
Description: Sample values:(“Card Not Present”,“Chip and Pin”,“Chip and Signature”,“Contactless”,“MastercardSecure”,“Mobile Purchase Authenticated”,“Other”,“Secured by AmericanExpress”,“SignatureOnly”,“Verified by Visa”)
avs Type: string
Description: Address Verification Status Code [A-Z]
bill_cycle Type: string
Description: How many times has this customer been billed (rebill depth)? (1. First month, or 2. Second month) Default to 1 if not provided
card Type: object
Description: An object representing the credit or debit card used to make the order/transaction
cascading_gateway Type: boolean
Description: Identifies if the orders for this client are processed through multiple payment gateways
checkout_account_ssn_last_four Type: string
Description: The last 4 digits of the customer’s social security number (SSN) (Optional for debit card payments)
checkout_last_four Type: string
Description: The last 4 digits of the checking account (optional for debit card payments)
cvv Type: string
Description: Cardholder Verification Value Status [0-9 or A-Z]. Note: Do NOT send the CVV code in this field, this value is the CVV status code sent back from the merchant’s payment gateway.
date_issued Type: string
Description: The date that the transaction was created/issued, this is usually the same as the order date. The settlement date or when funds were transferred into the merchant’s bank account is the settlement_date
decline_reason Type: string
Description: Indicates the authorization decline reason
device_id Type: string
Description: The mobile or computer device identifier (ID)
device_name Type: string
Description: Name of the mobile device type or type of computer used to process this transaction.
fraud_action Type: string
Description: Action taken if/when the transaction is identified as fraudulent.
fraud_filter Type: string
Description: The name of the fraud filter applied against the transaction.
fraud_score Type: string
Description: The fraud score assessed on this transaction [A-Z]
id Type: string
Description: ID of the transaction
Required: Yes
ip_address Type: string
Description: IP address of the customer who generated the transaction
market_type Type: string
Description: Valid market types:(“eCommerce”,“MOTO”,“Retail”)
mid Type: string
Description: The merchant account number or merchant identifier (MID) associated with this transaction
Required: Yes
mid_gateway_descriptor Type: string
Description: The MID descriptor is the text displayed on the customer’s credit card statement for this transaction.
mid_gateway_id Type: string
Description: The merchant’s payment gateway identifier (ID).
products Type: Array of objects
Description: An array of product objects purchased on this order.
rebill_discount_percent Type: string
Description: The percentage discount offered to clients who initially refused to continue a recurring /subscription service.
refund_amount Type: string
Description: The sum of all refunds on this order.
refund_date Type: string
Description: Date of the last refund for this order (*Required if refund_amount is provided)
retry_date Type: string
Description: The next date that a recurring subscription charge will be attempted (if previous charge failed)
routing_transit_number Type: string
Description: The bank routing number used in this transaction. Typically this is included with debit card purchases.
settlement_amount Type: string
Description: The amount paid to the merchant at the time of settlement.
Required: Yes
settlement_currency Type: string
Description: The type of currency used when the transaction was settled.
settlement_date Type: string
Description: The date the transaction was settled
Required: Yes
status Type: string
Description: The current status of the transaction, must match one of these values: (“Approved”,“Authorized”,“Declined”,“Duplicate”,“Error”,“Failed”,“Other”,“Refunded”,“Rejected”,“Success”)
void_amount Type: string
Description: The sum of all voids for the current order.
void_date Type: string
Description: Date of the last void for the current order (*Required if void_amount is provided)

Card Object (History)

Field Details
code_status Type: string
Description: For merchants who use Card Code Verification. This value represents the status value returned by the card network/scheme
exp_month Type: string
Description: Credit or debit card expiration month
exp_year Type: string
Description: Credit or debit card expiration year
number Type: string
Description: Credit or debit card number. Note: Only send the first 6 digits and the last 4 digits of the credit/debit number. The rest of the middle digits should be masked with x’s.
prepaid Type: boolean
Description: Is this a prepaid card? (true/false)
test Type: boolean
Description: Is this a test order? (true/false)
type Type: string
Description: Credit or debit card type (“Visa”, “MasterCard”, “Discover”, “Amex”)

Products Object (History)

Field Details
description Type: string
Description: Description of the product/service.
digital Type: object
Description: An object containing digital product/service details
has_rma Type: boolean
Description: Has a return been authorized on this product/service? (“true”/”false”)
id Type: string
Description: The merchant’s unique product/service identifier (ID).
Required: Yes
is_upsell Type: string
Description: Was this product/service an upsell?
name Type: string
Description: Name of the product or service.
price Type: string
Description: Price of the product/service.
product_group Type: string

Get a list of chargebacks

Please note that max. 2500 records will be returned per API call. Paginate using page filter parameters until no records returned as shown in the example below.

/v2/clients/{merchantId}/chargebacks?page=1...

/v2/clients/{merchantId}/chargebacks?page=2...

Users are encouraged to refine their searches using request parameters (filter criteria) like Acquirer Reference Numbers (ARN), case numbers or date range.

verdict and verdict_history are available based on account access. If you would like to know more, please reach out to your Account Relationship Manager.

Query Parameters

Parameter Type Example Description
arn string arn=98278274829743294525435 A 23-digit string integer that represents the Acquirer Reference Number (ARN)
bin string bin=438493 The first 6 digits on the credit card
case_no string case_no=EC2833 The unique case number
case_type string case_type=First Chargeback Case Type. Enum: "First Chargeback", "Retrieval Request", "Second Chargeback"
cc_type string cc_type=Visa Credit card type. Enum: "Amex", "Discover", "MasterCard", "Unknown", "Visa"
currency string currency=USD Transaction currency
date_column string date_column=date_trans The value of this field is used to search for date ranges. Enum: "date_created", "date_post", "date_trans", "date_updated"
date_created string date_created=2020-03-15 The date the chargeback was created in Chargebacks911
date_due string date_due=2020-02-14 Chargeback due date
date_post string date_post=2020-02-01 The date the chargeback was created by the card network/scheme
date_updated string date_updated=2020-02-01 The last date the chargeback was updated
end_date string end_date=2020-05-04 The ending date for searching by date
id integer id=123456 The unique identifier number for a chargeback
last_four string last_four=5345 The last 4 digits of the credit card related to the chargeback
limit string limit=20 Only retrieve results from the page number specified
mid string mid=21226255 The merchant account number or ID for the chargeback
page string page=4 Limit the number of results returned per page
reason_category string reason_category=Unauthorized transaction The reason category code provided by the card network/scheme as to the reason the chargeback was filed
reason_code string reason_code=4837 The reason code provided by the card network/scheme as to the reason the chargeback was filed
start_date string start_date=2020-01-01 The beginning date for searching by date
status any status=new The current status of the chargeback. Enum: "completed", "expired", "new", "not_represented"