Chargeback alert services, dispute tools, and outsourced support desks usually need the same four actions: find a transaction from the card details, refund it, leave a note on the customer, and mark the chargeback. This guide shows the call for each one, the API key it needs, and how to test the integration.

Step 1: Create the API Key

1. Go to Settings, click Account settings, and open the API Keys tab.

2. Click Add New and enter a Name that identifies the tool.

3. In Type, select Chargeback Defence. It can find transactions, refund them, and mark chargebacks, and nothing else.

4. Click Save and copy the key.

Step 2: Find the Transaction

Search by the last four digits of the card, the BIN, and a date range in Unix time (seconds):

$ curl -X GET 'https://openapi.admoji.com/api/v2/open/transactions?last4=4607&bin=411111&dateFromUtc=1790553600&dateToUtc=1790640000' \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111"

From each transaction in the response, keep these values for the next steps:

• TransactionGatewayID — identifies the charge in the refund and chargeback calls.

• CustomerID — identifies the customer in the note and chargeback calls.

• OrderInfo.OrderID — the order the charge belongs to.

• Keep the date range as narrow as the alert allows, and add amountfrom and amountto when you know the amount. The endpoint returns up to 1,000 transactions per call and accepts one call per second.

• Test transactions are left out unless you send testtype=test or testtype=all.

The full list of filters is in the API Reference.

Step 3: Refund or Void the Charge

$ curl -X POST 'https://openapi.admoji.com/api/v2/open/customer/refund' \
  -H "content-type: application/json" \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111" \
  -H "Idempotency-Key: 3a2ebd06-e52f-47d2-92c4-66a107022f8e" \
  -d '{
    "TransactionID": "3534881111",
    "Amount": 29.99,
    "Type": "refund"
  }'

• TransactionID — required. The TransactionGatewayID from Step 2.

• Amount — optional. Leave it out to refund the full amount.

• Type — optional. refund (default) or void.

A successful call answers { "Status": 0, "ResponseText": "SUCCESS" }. If the gateway rejects the refund, the call returns an error with the gateway's response text and the order is left as it was.

Step 4: Leave a Note on the Customer

This call needs a Full Access key.

$ curl -X POST 'https://openapi.admoji.com/api/v2/open/customers/notes/9031111' \
  -H "content-type: application/json" \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111" \
  -H "Idempotency-Key: 7c1d9e52-0b6a-4f3e-8a41-2f5b6c7d8e90" \
  -d '{
    "Note": "Refunded after an alert from the dispute tool",
    "OrderID": 111222333
  }'

The customer ID goes in the URL. Note is required, up to 512 characters. OrderID is optional and ties the note to one order of that customer. See How to Add and View Notes on a Customer or Order.

Step 5: Mark the Chargeback

$ curl -X POST 'https://openapi.admoji.com/api/v2/open/customers/mark-chargeback' \
  -H "content-type: application/json" \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111" \
  -H "Idempotency-Key: b2f0a6c4-91d3-4e7a-a5c8-3d4e5f607182" \
  -d '{
    "CustomerID": 9031111,
    "Option": "cb",
    "GatewayTransactionID": "3534881111",
    "Note": "Chargeback received from Visa"
  }'

Option is cb for a chargeback, cbalert for a chargeback alert, or refund to flag the customer as refunded.

Testing the Integration

There is no separate sandbox account: you test inside the live account with test cards.

1. Add cards to the list in Settings > Account settings > Test Cards. See How to Use Test Cards.

2. Place an order with one of those cards. It is approved or declined inside Admoji and never reaches the gateway.

3. Run the calls above against that order, adding testtype=test to the search in Step 2.

Related articles

• API Reference

• API Key Types Explained

• How to Find your API Key

• How to Mark a Chargeback with the API

• How to Use Test Cards