Back to top

Chargeback API

The Chargeback API is a collection of RESTful JSON calls. The API uses standardized HTTP verbs and resource routes. Whenever possible, all JSON results will use a standardized format.

Authentication

The Chargeback API uses HTTP Basic Authentication. Depending on the access controls granted to the key authorizing the request, some actions may be unavailable.

Orders

Verb Action Route Purpose
GET search /orders Search existing orders (see Orders section for search keys and return values)
GET show /orders/(id) Retrieve information about a single order
POST create /orders Create a new order.
PUT/PATCH update /orders/(id) Update an existing order with new information

Order Object

An Order object represents a single sales order in the ecommerce platform, POS system, or sales platform for the merchant. It has the following attributes:

Attributes

Key Type Importance Description
order_id string REQUIRED The merchant system’s unique identifier for the order
order_ts ISO 8601 REQUIRED The merchant system’s “order completed” timestamp
order_amount decimal REQUIRED The final total amount of the order
transaction_id string REQUIRED The transaction id in the payment gateway for the credit card transaction
transaction_amount decimal REQUIRED The amount charged in the payment gateway for the credit card transaction.
crm_id, crm_name integer / string REQUIRED Chargeback’s identifier for the data source, or the name of the data source (agreed upon beforehand)
merchant_name integer / string REQUIRED Chargeback’s identifier for the merchant, or the name of the merchant.
card_prefix 6 numerical digits RECOMMENDED The first six digits of the card number. Alternatively, use the card_number field.
card_suffix 4 numerical digits RECOMMENDED The last four digits of the card number. Alternatively, use the card_number field.
card_type string (derived) The card network of the card used in the transaction. If not passed, Chargeback will ascertain based on card #
card_exp MM/YY RECOMMENDED The expiration date captured at time of sale
reported_avs_status string RECOMMENDED If captured, the AVS status of the transaction
reported_cvv_status string RECOMMENDED If captured, the CVV status of the transaction
currency_code ISO 4217 (string) Defaults to USD
ip_address dotted quad RECOMMENDED The IP used by the cardholder to place the order in the merchant’s sales platform. Will be compared with billing and shipping addresses.
authorization_code string RECOMMENDED If captured, the authorization code returned by the gateway
arn string RECOMMENDED The ARN, if known
shipping_subtotal decimal The amount charged for shipping.
tax_subtotal decimal The amount charged for tax
source_url string The url to access this order in the merchant’s sales platform.
tracking_numbers comma list RECOMMENDED Comma-separated list of tracking numbers; each will generate new shipment objects.
line_items array RECOMMENDED Line items on the order; see line items section for object details
shipments array RECOMMENDED Shipping info on the order; see shipments section for object details

Customer Profile

If the customer is a registered user in your system, pass the customer profile information

Key Type Importance
customer_email string RECOMMENDED
customer_last_name string RECOMMENDED
customer_first_name string RECOMMENDED
customer_phone string RECOMMENDED

Billing Info

The billing information captured for this particular transaction

Key Type Importance
billing_last_name string RECOMMENDED
billing_first_name string RECOMMENDED
billing_address1 string RECOMMENDED
billing_address2 string RECOMMENDED
billing_city string RECOMMENDED
billing_state string RECOMMENDED
billing_country string RECOMMENDED
billing_postal string RECOMMENDED

System Fields

These fields are either computed, derived, or stored internally by chargeback, but may prove useful to some merchants. If submitted to the api, they will be ignored.

Key Type Description
id integer Chargeback’s unique identifier for this order (maybe be used for updates)
avs_status string Normalized version of the reported_avs_status, if recognized
cvv_status string Normalized version of the reported_cvv_status, if recognized
created_at ISO 8601 The time in UTC when the order record was originally added to the database
updated_at ISO 8601 The last time in UTC when the order record was modified
creator_id integer The id of the creator of the record. For API calls, it will be the user record that authorized the call
creator_type string The type of creator of the record. For API calls, it will be the string ‘User’
manually_generated boolean This will only be set to true for records created in the web UI

Line Items

The line items on the order; the products that were actually sold. line_items should be an array of json objects.

Key Type Importance Description
product_name RECOMMENDED The name of the product sold, as it stood at the time of the order.
product_description RECOMMENDED The description of the product, as it stood at the time of the order.
product_amount decimal RECOMMENDED The price of the product at the time of the order.
quantity integer RECOMMENDED The number of this line item sold.
subtotal decimal RECOMMENDED Should be equal to quantity * subtotal. Can be computed from these if left blank.
source_product_id string RECOMMENDED The unique identifier of the product in the source system’s backend database

Shipments

This object is returned as and array of shipping information that was pulled based on the tracking numbers passed in. You can also just pass in shipments.

Key Type Description
tracking_number string Tracking number that identifies this shipment
shipper_name string Name of the shipper
shipped_ts string When the shipment shipped
origin_name string
origin_address1 string
origin_address2 string
origin_city string
origin_state string
origin_country string
origin_zip string
destination_first_name string
destination_last_name string
destination_address1 string
destination_address2 string
destination_city string
destination_state string
destination_country string
destination_zip string

Search / List Orders
GET/orders

Search existing orders that your api user is authorized to view.

Example URI

GET https://app.chargeback.com/api/v1/orders
URI Parameters
HideShow
page
integer (optional) Example: 1

What page you want

per_page
integer (optional) Example: 20

How many orders will be returned. This may not be above 100.

search
json (optional) 

Search parameters for the call, see orders object for fields that you can sort by.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    status: 'success',
    page: '1',
    per_page: '20',
    total_records: '1',
    orders: [...]
}

Get an existing Order
GET/orders/(id)

You may view an existing Order record and its details.

Example URI

GET https://app.chargeback.com/api/v1/orders/(id)
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
    'status': 'success',
    'order': {
        'id' : '12345678',
        'order_id' : 'abc123',
        'customer_email' : 'example@email.com',
        'ip_address' : '172.98.44.123',
        'order_ts' : '2017-11-27T23:59:26Z',
        'created_at' : '2017-11-28T00:01:42Z',
        'updated_at' : '2017-11-28T00:01:42Z',
        'order_amount' : '177.16',
        'customer_first_name' : 'Nate',
        'customer_last_name' : 'Smith',
        'billing_first_name' : 'Nate',
        'billing_last_name' : 'Smith',
        'billing_address1' : '12345 My Actual House',
        'billing_city' : 'South Jordan',
        'billing_state' : 'UT',
        'billing_country' : 'USA',
        'billing_postal' : '84009',
        'authorization_code' : 'xxyyzz',
        'card_type' : 'Visa',
        'card_prefix' : '444321',
        'card_suffix' : '8215',
        'shipping_subtotal' : '5.00',
        'tax_subtotal' : '5.00',
        'manually_generated' : false,
        'creator_type' : 'ApiUser',
        'source_url' : 'https://my-magento-site.com/admin-area/order-search.php?order_id=abc123',
        'customer_phone' : '123-456-7890',
        'transaction_id' : 'qwertyzzz',
        'transaction_amount' : '55.00',
        'cvv_status' : 'M',
        'currency_code' : 'USA',
        'card_exp' : '05/21',
        'reported_avs_status' : 'Y',
        'avs_status' : 'Y',
        'tracking_numbers' : '1ZY2F2150255600110',
        'line_items' : [
            {
                'product_name' : 'MIRRORLESS MICRO FOUR THIRDS 45-150 MM',
                'product_description' : 'PANASONIC LUMIX G VARIO LENS, 45-150MM, F4.0-5.6 ASPH., MIRRORLESS MICRO FOUR THIRDS, MEGA OPTICAL I.S., H-FS45150AK (USA BLACK)',
                'product_amount' : '147.99',
                'quantity' : 1,
                'subtotal' : '147.99',
                'source_product_id' : 'prod-123'
            },
            {
                'product_name' : 'Lens Cap',
                'product_description' : 'Lens cap with lanyard fits most panasonic lumix cameras',
                'product_amount' : '5.99',
                'quantity' : 2,
                'subtotal' : '11.98',
                'source_product_id' : 'prod-777'
            }
        ],
        'crm' : {
            'id': 444,
            'name': 'crm_name'
        },
        'merchant' : {
            'name': 'your_merchant_name'
        },
        'shipments' : [
            {
                'tracking_number' : '1ZY2F2150255600110',
                'tracking_summary': null,
                'shipper_name' : 'UPS',
                'shipped_ts' : null,
                'origin_name' : 'Cameras R Us',
                'origin_address1' : '555 A Texas Road',
                'origin_city' : 'Austin',
                'origin_state' : 'TX',
                'origin_country' : 'USA',
                'origin_zip' : '73301',
                'destination_first_name' : 'Nate'
                'destination_last_name' : 'Smith',
                'destination_address1' : '10235 S. Jordan Gateway',
                'destination_address2' : 'Suite 500',
                'destination_city' : 'South Jordan',
                'destination_state' : 'UT',
                'destination_country' : 'USA',
                'destination_zip' : '84095',
            }
        ]
    }
}

Create a New Order
POST/orders

You may report a completed Order using this action. It takes a JSON object.

Example URI

POST https://app.chargeback.com/api/v1/orders
Request
HideShow
Headers
Content-Type: application/json
Body
{
        'status': 'success',
        'order': {
            'crm_id' : 444,
            'merchant_name' : 'your_merchant_name',
            'order_id' : 'abc123',
            'order_ts' : '2017-11-27T23:59:26Z',
            'customer_email' : 'example@email.com',
            'order_amount' : '177.16',
            'transaction_id' : 'qwertyzzz',
            'transaction_amount' : '55.00',
            'card_prefix' : '444321',
            'card_suffix' : '8215',
            'card_exp' : '05/21',
            'reported_avs_status' : 'Y',
            'reported_cvv_status' : 'M',
            'ip_address' : '172.98.44.123',
            'authorization_code' : 'xxyyzz',
            'shipping_subtotal' : '5.00',
            'tax_subtotal' : '5.00',
            'source_url' : 'https://my-magento-site.com/admin-area/order-search.php?order_id=abc123',
            'tracking_numbers' : '1ZY2F2150255600110',
            'line_items' : [
                {
                    'product_name' : 'MIRRORLESS MICRO FOUR THIRDS 45-150 MM',
                    'product_description' : 'PANASONIC LUMIX G VARIO LENS, 45-150MM, F4.0-5.6 ASPH., MIRRORLESS MICRO FOUR THIRDS, MEGA OPTICAL I.S., H-FS45150AK (USA BLACK)',
                    'product_amount' : '147.99',
                    'quantity' : 1,
                    'subtotal' : '147.99',
                    'source_product_id' : 'prod-123'
                },
                {
                    'product_name' : 'Lens Cap',
                    'product_description' : 'Lens cap with lanyard fits most panasonic lumix cameras',
                    'product_amount' : '5.99',
                    'quantity' : 2,
                    'subtotal' : '11.98',
                    'source_product_id' : 'prod-777'
                }
            ],
            'customer_first_name' : 'Nate',
            'customer_last_name' : 'Smith',
            'billing_first_name' : 'Nate',
            'billing_last_name' : 'Smith',
            'billing_address1' : '12345 My Actual House',
            'billing_city' : 'South Jordan',
            'billing_state' : 'UT',
            'billing_country' : 'USA',
            'billing_postal' : '84009',
        }
    }
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
    'status': 'success',
    'order': {
        'id' : '12345678',
        'order_id' : 'abc123',
        'customer_email' : 'example@email.com',
        'ip_address' : '172.98.44.123',
        'order_ts' : '2017-11-27T23:59:26Z',
        'created_at' : '2017-11-28T00:01:42Z',
        'updated_at' : '2017-11-28T00:01:42Z',
        'order_amount' : '177.16',
        'customer_first_name' : 'Nate',
        'customer_last_name' : 'Smith',
        'billing_first_name' : 'Nate',
        'billing_last_name' : 'Smith',
        'billing_address1' : '12345 My Actual House',
        'billing_city' : 'South Jordan',
        'billing_state' : 'UT',
        'billing_country' : 'USA',
        'billing_postal' : '84009',
        'authorization_code' : 'xxyyzz',
        'card_type' : 'Visa',
        'card_prefix' : '444321',
        'card_suffix' : '8215',
        'shipping_subtotal' : '5.00',
        'tax_subtotal' : '5.00',
        'manually_generated' : false,
        'creator_type' : 'ApiUser',
        'source_url' : 'https://my-magento-site.com/admin-area/order-search.php?order_id=abc123',
        'customer_phone' : '123-456-7890',
        'transaction_id' : 'qwertyzzz',
        'transaction_amount' : '55.00',
        'cvv_status' : 'M',
        'currency_code' : 'USA',
        'card_exp' : '05/21',
        'reported_avs_status' : 'Y',
        'avs_status' : 'Y',
        'tracking_numbers' : '1ZY2F2150255600110',
        'line_items' : [
            {
                'product_name' : 'MIRRORLESS MICRO FOUR THIRDS 45-150 MM',
                'product_description' : 'PANASONIC LUMIX G VARIO LENS, 45-150MM, F4.0-5.6 ASPH., MIRRORLESS MICRO FOUR THIRDS, MEGA OPTICAL I.S., H-FS45150AK (USA BLACK)',
                'product_amount' : '147.99',
                'quantity' : 1,
                'subtotal' : '147.99',
                'source_product_id' : 'prod-123'
            },
            {
                'product_name' : 'Lens Cap',
                'product_description' : 'Lens cap with lanyard fits most panasonic lumix cameras',
                'product_amount' : '5.99',
                'quantity' : 2,
                'subtotal' : '11.98',
                'source_product_id' : 'prod-777'
            }
        ],
        'crm' : {
            'id': 444,
            'name': 'crm_name'
        },
        'merchant' : {
            'name': 'your_merchant_name'
        },
        'shipments' : [
            {
                'tracking_number' : '1ZY2F2150255600110',
                'tracking_summary': null,
                'shipper_name' : 'UPS',
                'shipped_ts' : null,
                'origin_name' : 'Cameras R Us',
                'origin_address1' : '555 A Texas Road',
                'origin_city' : 'Austin',
                'origin_state' : 'TX',
                'origin_country' : 'USA',
                'origin_zip' : '73301',
                'destination_first_name' : 'Nate'
                'destination_last_name' : 'Smith',
                'destination_address1' : '10235 S. Jordan Gateway',
                'destination_address2' : 'Suite 500',
                'destination_city' : 'South Jordan',
                'destination_state' : 'UT',
                'destination_country' : 'USA',
                'destination_zip' : '84095',
            }
        ]
    }
}

Update an existing Order
PUT/orders/(id)

You may update information about an Order already reported to Chargeback using this action. You must specify the Order based on Chargeback’s unique identifier (id) for the Order.

Example URI

PUT https://app.chargeback.com/api/v1/orders/(id)
Request
HideShow
Headers
Content-Type: application/json
Body
{
    'id' : 12345678,
    'billing_address1' : '12345 a different address',
    'billing_city' : 'Another City',
    'billing_state' : 'CA',
    'billing_country' : 'USA',
    'billing_postal' : '90233'
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
    'status': 'success',
    'order': {
        'id' : '12345678',
        'order_id' : 'abc123',
        'customer_email' : 'example@email.com',
        'ip_address' : '172.98.44.123',
        'order_ts' : '2017-11-27T23:59:26Z',
        'created_at' : '2017-11-28T00:01:42Z',
        'updated_at' : '2017-11-28T00:01:42Z',
        'order_amount' : '177.16',
        'customer_first_name' : 'Nate',
        'customer_last_name' : 'Smith',
        'billing_first_name' : 'Nate',
        'billing_last_name' : 'Smith',
        'billing_address1' : '12345 a different address',
        'billing_city' : 'Another City',
        'billing_state' : 'CA',
        'billing_country' : 'USA',
        'billing_postal' : '90233'
        'authorization_code' : 'xxyyzz',
        'card_type' : 'Visa',
        'card_prefix' : '444321',
        'card_suffix' : '8215',
        'shipping_subtotal' : '5.00',
        'tax_subtotal' : '5.00',
        'manually_generated' : false,
        'creator_type' : 'ApiUser',
        'source_url' : 'https://my-magento-site.com/admin-area/order-search.php?order_id=abc123',
        'customer_phone' : '123-456-7890',
        'transaction_id' : 'qwertyzzz',
        'transaction_amount' : '55.00',
        'cvv_status' : 'M',
        'currency_code' : 'USA',
        'card_exp' : '05/21',
        'reported_avs_status' : 'Y',
        'avs_status' : 'Y',
        'tracking_numbers' : '1ZY2F2150255600110',
        'line_items' : [
            {
                'product_name' : 'MIRRORLESS MICRO FOUR THIRDS 45-150 MM',
                'product_description' : 'PANASONIC LUMIX G VARIO LENS, 45-150MM, F4.0-5.6 ASPH., MIRRORLESS MICRO FOUR THIRDS, MEGA OPTICAL I.S., H-FS45150AK (USA BLACK)',
                'product_amount' : '147.99',
                'quantity' : 1,
                'subtotal' : '147.99',
                'source_product_id' : 'prod-123'
            },
            {
                'product_name' : 'Lens Cap',
                'product_description' : 'Lens cap with lanyard fits most panasonic lumix cameras',
                'product_amount' : '5.99',
                'quantity' : 2,
                'subtotal' : '11.98',
                'source_product_id' : 'prod-777'
            }
        ],
        'crm' : {
            'id': 444,
            'name': 'crm_name'
        },
        'merchant' : {
            'name': 'your_merchant_name'
        },
        'shipments' : [
            {
                'tracking_number' : '1ZY2F2150255600110',
                'tracking_summary': null,
                'shipper_name' : 'UPS',
                'shipped_ts' : null,
                'origin_name' : 'Cameras R Us',
                'origin_address1' : '555 A Texas Road',
                'origin_city' : 'Austin',
                'origin_state' : 'TX',
                'origin_country' : 'USA',
                'origin_zip' : '73301',
                'destination_first_name' : 'Nate'
                'destination_last_name' : 'Smith',
                'destination_address1' : '10235 S. Jordan Gateway',
                'destination_address2' : 'Suite 500',
                'destination_city' : 'South Jordan',
                'destination_state' : 'UT',
                'destination_country' : 'USA',
                'destination_zip' : '84095',
            }
        ]
    }
}

Delete an existing order
DELETE/orders/(id)

You may only delete orders that were created using the api and are not currently part of a response

Example URI

DELETE https://app.chargeback.com/api/v1/orders/(id)
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
    'status': :'success'
}

Transactions

Transaction

A Transaction object represents a single credit card transaction in the payment gateway.

Disputes

Dispute

A Dispute is a retrieval request, chargeback, or pre_arbitration / second chargeback reported by the payment processor.

Alerts

Alert

An Alert notifies of a pending chargeback.

Mids

Mid

The MID, or Merchant ID, is an identifier for the merchant account. Since larger merchants often use many MIDs, you can use the MID endpoints to keep Chargeback up-to-date with the MIDs you are using.

Generated by aglio on 04 Jun 2018