Payments: Transactions

Modified on Tue, 16 Apr 2024 at 05:39 PM

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

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


Currently ACME handles 3 types of transactions:  

  • Sale (sale_)
  • Refund (refund_)
  • Chageback (chbk_)


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/{MID}/transaction

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": "sale_32ae32ce-835b-4167-a692-57e867e9a720",
        "externalId": "extId-QA1234",
        "type": "Sale",
        "fundsDirection": "Positive",
        "createdOn": "2024-03-29T19:01:02-05:00",
        "paymentMethod": "CreditCard",
        "readMethod": "Card not present",
        "card":
        {
            "lastFour": "3333",
            "expirationDate":
            {
                "month": "12",
                "year": "2024"
            },
            "address1": "111 Runner Road",
            "postalCode": "95555",
            "brand": "Visa"
        },
        "amount":
        {
            "totalAmount": "2.70",
            "netAmount": "2.32",
            "fee":
            {
                "totalFee": "0.38",
                "fixedFee": "0.30",
                "percentageFee": "0.08",
                "percentageRate": "2.90"
            }
        },
        "externalPaymentMethodId": "ext-1faaa171-8aaf-40c4-8297-2b6d37e4f3a8",
        "externalCustomerId": "WPExtCustID-123",
        "email":"email@acmeticketing.com",
        "externalTransactionId": "9876543210098"
    },
    {
        "id": "refund_56b8832c-7988-4010-ba5f-e8370aeebe0f",
        "request":
        {
            "saleId": "sale_32ae32ce-835b-4167-a692-57e867e9a720",
            "createdOn": "2024-03-29T19:01:02-05:00",
            "updatedOn": "2024-03-29T19:01:05-05:00"
        },
        "type": "Refund",
        "fundsDirection": "Negative",
        "createdOn": "2024-03-29T19:02:22-05:00",
        "paymentMethod": "CreditCard",
        "card":
        {
            "lastFour": "3333",
            "expirationDate":
            {
                "month": "12",
                "year": "2024"
            },
            "address1": "111 Runner Road",
            "postalCode": "95555",
            "brand": "Visa"
        },
        "amount":
        {
            "totalAmount": "2.70",
            "netAmount": "2.32",
            "fee":
            {
                "totalFee": "0.38",
                "fixedFee": "0.30",
                "percentageFee": "0.08",
                "percentageRate": "2.90"
            }
        }
    },
    {
        "id": "sale_806c842b-7d1e-4615-9ca7-4c60b85657f2",
        "externalId": "extId-QA1234",
        "type": "Sale",
        "fundsDirection": "Positive",
        "createdOn": "2024-03-29T19:24:31-05:00",
        "paymentMethod": "CreditCard",
        "readMethod": "Card not present",
        "card":
        {
            "lastFour": "3333",
            "expirationDate":
            {
                "month": "12",
                "year": "2026"
            },
            "address1": "111 Runner Road",
            "postalCode": "95555",
            "brand": "Visa"
        },
        "amount":
        {
            "totalAmount": "2.70",
            "netAmount": "2.32",
            "fee":
            {
                "totalFee": "0.38",
                "fixedFee": "0.30",
                "percentageFee": "0.08",
                "percentageRate": "2.90"
            }
        },
        "externalPaymentMethodId": "ext-054fa966-4e02-40c0-a3fa-397f5917e5c8",
        "externalCustomerId": "WPExtCustID-123",
        "email":"email@acmeticketing.com",
        "externalTransactionId": "9876543210098"
    }],
    "pagination":
    {
        "page": 1,
        "pageSize": 100,
        "sortDirection": "asc",
        "sortField": "createdOn",
        "hasMore": false
    }
} %    

JavaScript




Retrieving a Sale, Refund or Chargeback 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.

ChbkId is used to request information about a chargeback that was filed against a transaction that was processed automatically and the amount returned to the customer.

Sample Request

GET https://sandX-api.acmepayments.net/12345/transaction/sale_2fffa3ac-269d-4952-800b-c2c593c844d4

HTML

Response

The corresponding Transaction object.

Sample Response Body

Single Sale Transaction

{
    "id": "sale_72a57412-04bf-4803-9667-369cd414a07f",
    "externalId": "extId-QA1234",
    "type": "Sale",
    "fundsDirection": "Positive",
    "createdOn": "2024-03-29T20:09:07-05:00",
    "paymentMethod": "CreditCard",
    "readMethod": "Card not present",
    "card":
    {
        "lastFour": "3333",
        "expirationDate":
        {
            "month": "12",
            "year": "2026"
        },
        "address1": "111 Runner Road",
        "postalCode": "95555",
        "brand": "Visa"
    },
    "amount":
    {
        "totalAmount": "2.70",
        "netAmount": "2.32",
        "fee":
        {
            "totalFee": "0.38",
            "fixedFee": "0.30",
            "percentageFee": "0.08",
            "percentageRate": "2.90"
        }
    },
    "externalPaymentMethodId": "ext-054fa966-4e02-40c0-a3fa-397f5917e5c8",
    "externalCustomerId": "WPExtCustID-123",
    "email":"email@acmeticketing.com",
    "externalTransactionId": "9876543210098"
}

JavaScript

Single Refund Transaction

{
    "id": "refund_56b8832c-7988-4010-ba5f-e8370aeebe0f",
    "request":
    {
        "saleId": "sale_32ae32ce-835b-4167-a692-57e867e9a720",
        "createdOn": "2024-03-29T19:01:02-05:00",
        "updatedOn": "2024-03-29T19:01:05-05:00"
    },
    "type": "Refund",
    "fundsDirection": "Negative",
    "createdOn": "2024-03-29T19:02:22-05:00",
    "paymentMethod": "CreditCard",
    "readMethod": "Card not present",
    "card":
    {
        "lastFour": "3333",
        "expirationDate":
        {
            "month": "12",
            "year": "2024"
        },
        "address1": "111 Runner Road",
        "postalCode": "95555",
        "brand": "Visa"
    },
    "amount":
    {
        "totalAmount": "2.70",
        "netAmount": "2.32",
        "fee":
        {
            "totalFee": "0.38",
            "fixedFee": "0.30",
            "percentageFee": "0.08",
            "percentageRate": "2.90"
        }
    }
}

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

email
email Address
Email submitted with original transaction

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

optional fee
string
An optional fee that might be applied at time of transaction creation.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article