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 OrdersGET/orders
Search existing orders that your api user is authorized to view.
Example URI
- page
integer
(optional) Example: 1What page you want
- per_page
integer
(optional) Example: 20How 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.
200
Headers
Content-Type: application/json
Body
{
status: 'success',
page: '1',
per_page: '20',
total_records: '1',
orders: [...]
}
Get an existing OrderGET/orders/(id)
You may view an existing Order record and its details.
Example URI
201
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 OrderPOST/orders
You may report a completed Order using this action. It takes a JSON object.
Example URI
Headers
Content-Type: application/json
Body
{
'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',
}
201
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',
}
]
}
}
Bulk create ordersPOST/orders
You may report multiple completed Orders using this action as well. It takes a JSON object.
You many only post 100 orders at a time
Example URI
Headers
Content-Type: application/json
Body
[{
'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',
}]
201
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 OrderPUT/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
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'
}
201
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 orderDELETE/orders/(id)
You may only delete orders that were created using the api and are not currently part of a response
Example URI
201
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.