Payments: Transactions

Modified on Fri, 08 Sep 2023 at 01:08 PM

Transactions are the interactions between your sellers and their customers, this API enables their lifecycle.

It requires your MerchantID {mid} in the URL and PaymentKey as a request header.

Get a List of Transactions

This allows you to pull all transactions associated with this {mid} in a paginated response.

GET v1/payment/{mid}/transaction

HTML

Request Parameters

The {mid} is the merchant ID of the seller that the transactions are associated with.

Query String Parameters

Field	Type	Description	Default
startTime	date	ISO8601 date of transactions you want after this time with the client timezone	24 hours before
endTime	date	ISO8601 date of transactions you want before this time with the client timezone. Max number of days is 45 days.	current date
page	number	The page that you want to retrieve	1st page
pageSize	number	The number of transactions to return per page. Maximum is 500 pages.If a larger number is entered, it will be reduced to 500.	100 tr
sortDirection	string	Results sorting direction (“asc” or “desc”)	ascending
sortField	string	Field to sort on. CreatedOn is the only supported field.	createdOn
type	string	Filtering to only return one transaction type: 'Sale' or 'Refund'	will return both sale and refund transactions

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/987654321/transaction?startTime=2021-11-18T08:00:00-08:00&endTime=2021-11-19T08:00:00-08:00&page=1&pageSize=50&type=Refund&sortDirection=desc

HTML

This will return the refund transactions that happened on November 18th 2021; first page with up to 50 records.

Response

Returns a list of Transactions that were processed by a particular seller

Transaction List

{
    "list": [
        {
            "id": "refund_d3f127f5-7bda-41bb-9fbd-c055f7d6f2a6",
            "request": {
                "saleId": "sale_c8fdc793-bbc2-4538-90fa-84837d0551bd",
                "createdOn": "2021-11-18T16:43:37-08:00",
                "updatedOn": "2021-11-18T16:43:37-08:00"
            },
            "type": "Refund",
            "createdOn": "2021-11-18T16:43:57-08:00",
            "paymentMethod": "CreditCard",
            "card": {
               "lastFour": "4242",
               "expirationDate": {
                  "month": "01",
                  "year": "2023"
                  },
           "postalCode": "T1X 0V6",
           "brand": "Visa",
           "firstName": "VISA",
           "lastName": "CARDHOLDER"
    },
            "amount": {
                "totalAmount": "74.00",
                "netAmount": "73.20",
                "fee": {
                    "totalFee": "0.80",
                    "fixedFee": "0.43",
                    "percentageFee": "0.37",
                    "percentageRate": "0.50"
                }
            }
        },
        {
            "id": "refund_c262ab5f-ef99-4dee-b139-b6307a270992",
            "request": {
                "saleId": "sale_769c90fb-aaa5-4943-ad88-6b6550c74085",
                "createdOn": "2021-11-19T11:07:23-08:00",
                "updatedOn": "2021-11-19T11:07:23-08:00"
            },
            "type": "Refund",
            "createdOn": "2021-11-19T11:10:29-08:00",
            "paymentMethod": "CreditCard",
            "card": {
               "lastFour": "4242",
               "expirationDate": {
                  "month": "01",
                  "year": "2023"
                   },
           "postalCode": "T1X 0V6",
           "brand": "Visa",
           "firstName": "VISA",
           "lastName": "CARDHOLDER"
            },
            "amount": {
                "totalAmount": "100.00",
                "netAmount": "98.83",
                "fee": {
                    "totalFee": "1.17",
                    "fixedFee": "0.67",
                    "percentageFee": "0.50",
                    "percentageRate": "0.50"
                }
            }
        }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 2,
        "sortDirection": "asc",
        "sortField": "createdOn",
        "hasMore": true
    }
}

JavaScript

Retrieving a Sale or Refund Transaction by ID

GET v1/payment/{mid}/transaction/{id}

HTML

Request Parameters

The {mid} is the merchant ID of the seller that the transaction is associated with.
The {id} (saleId or refundId) in the URL of the request. The saleId was returned in a successful sale transaction call. The refundId was returned in a successful refund a payment call.

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/12345/transaction/sale_a71b4398-91f8-446f-b5cb-547f

HTML

Response

The corresponding Transaction object.

Sample Response Body

Single Sale Transaction

{
    "id": "sale_a71b4398-91f8-446f-b5cb-547f4395feee",
    "type": "Sale",
    "createdOn": "2021-11-08T10:00:00-08:00",
    "paymentMethod": "CreditCard",
    "readMethod": "Card not present",
    "card": {
        "lastFour": "4242",
        "expirationDate": {
            "month": "01",
            "year": "2023"
        },
        "postalCode": "T1X 0V6",
        "brand": "Visa",
        "firstName": "VISA",
        "lastName": "CARDHOLDER"
    },
    "amount": {
        "totalAmount": "174.00",
        "netAmount": "172.13",
        "fee": {
            "totalFee": "1.87",
            "fixedFee": "1.00",
            "percentageFee": "0.87",
            "percentageRate": "0.50"
        }
    }
}

JavaScript

Single Refund Transaction

{
    "id": "refund_5f35c134-21d1-48b8-9dc2-aa3d50a8f515",
    "request": {
        "saleId": "sale_b75fe81e-afc9-4868-a6f0-962931b03631",
        "createdOn": "2022-01-12T13:21:41-08:00",
        "updatedOn": "2022-01-12T13:21:41-08:00"
    },
    "type": "Refund",
    "createdOn": "2022-01-12T16:02:15-08:00",
    "paymentMethod": "CreditCard",
    "card": {
        "lastFour": "4242",
        "expirationDate": {
            "month": "12",
            "year": "2023"
        },
        "postalCode": "T1X 0V6",
        "brand": "Visa"
    },
    "amount": {
        "totalAmount": "20.00",
        "netAmount": "19.72",
        "fee": {
            "totalFee": "0.28",
            "fixedFee": "0.18",
            "percentageFee": "0.10",
            "percentageRate": "0.50"
        }
    }
}

JavaScript

Retrieving Sale Transactions and Refunds by External ID

GET v1/payment/{mid}/transaction/ext/{externalId}

HTML

Request Parameters

The {mid} is the merchant ID of the seller that the transaction is associated with.
The {externalId} in the URL of the request. The externalId was supplied in a successful sale transaction call.

Sample Request

GET https://sandX-api.acmepayments.net/v1/payment/12345/transaction/ext/order-123

HTML

Response

Returns a list of the sale transactions and any associated refunds, sorted by the field createdOn (ascending).

Transaction Object

Name	Type	Description
id	string	A unique ID for this transaction
type	string	'Sale' or 'Refund'
request	Original Sale Object	Original Sale Object containing the details of the sale associated with a refund. Will not be returned when getting a Sale Transaction.
createdOn	ISO date	The Date this transaction was created as a Date Object. includes the offset so when a timezone is passed in it will be returned with the right offset
paymentMethod	string	Currently only Credit Card is supported
readMethod	string	Method that the card was used during a sale transaction. Fields other than “Card Not Present” are only applicable when transacting on a device via the SDK. This will not be present in a refund transaction. Swipe - Swiping a card using the magnetic stripe reader Insert - Inserting a chip card into the card reader Contactless - Tapping a contactless-enabled chip card or mobile wallet Swipe Fallback - When inserting a chip card fails three times in a row, fallback to a magnetic stripe read Contactless Swipe - Older standard for contactless payments that emulated a magnetic stripe read Card Not Present - online or manual entry
amount	Amount Object	An amount object for this transaction
card	Card Object ›	The card object that includes credit card information used for this transaction

Original Sale Object (Request)

Name	Type	Description
saleId	string	ID of the sale transaction this refund is associated to
createdOn	ISO date	Date the sale was created on
updatedOn	ISO date	Date the sale was last updated

Amount Object

Name	Type	Description
totalAmount	string	The total amount as a decimal number
Fee	Fee Object	Fee object containing the details of the fees
netAmount	string	The amount after the fees have been deducted.

Fee Object

Name	Type	Description
totalFee	string	The total amount of the fee
fixedFee	string	The amount of the fee that was due to a fixed rate
percentageFee	string	The amount of the fee that was due to a percent rate
percentageRate	string	The percentage that was used to calculate the fee