Website logo

Get your ping balance ledger

Gets the ping balance ledger for the logged in member

URL: https://api.trademe.co.nz/v1/Ping/Transactions.{file_format}
HTTP Method: GET
Requires Authentication? Yes
Permission Required: MyTradeMeRead: Read your membership & listing data.
Supported Formats: XML, JSON
Rate Limited? Yes

URL parameters

file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

Query String parameters

date_from DateTime (optional)

Exclude transactions before this date. Specify dates in the UTC time zone.

date_to DateTime (optional)

Exclude transactions after this date. Specify dates in the UTC time zone.

page Integer (optional)

The page number of the set of results to return, starting from 1. Defaults to 1.

rows Integer (optional)

The number of results per page; also the maximum number of results to return. Defaults to 50 and supports a maximum of 50

Returns

<BalanceLedgerResponse>

TotalCount Integer

The total number of results in the collection. Can be larger than the number of returned results.

Page Integer

The index of the current page of results (starts at 1).

PageSize Integer

The number of results in the current page.

List Collection of <Transaction> or null

A list of the results in the current page.

TransactionId Long Integer or null

Ping transaction ID.

TransactionType Enumeration

Ping transaction type.

Purchase 0

Purchase made as a buyer

PurchaseReverse 1

Purchase made as a buyer - reversed by Trust and Safety

Sale 2

Sale made as a seller

SaleReverse 3

Sale made as a seller - reversed by Trust and Safety

RefundToAccount 4

Refund given as a seller

RefundFromAccount 5

Refund received as a buyer

Withdrawal 6

Ping balance transfer out

WithdrawalReverse 7

Ping balance transfer out - reversed by Trust and Safety

PurchaseRelease 8

Purchase release

SaleRelease 9

Sale release

CartPurchase 10

Cart purchase made as a buyer

CartSale 11

Cart Sale transaction

Peer 12

Peer to Peer transaction, Donations will appear as Peer to Peer

CartPurchaseReverse 13

Cart purchase made as a buyer - reversed by Trust and Safety

RefundToAccountReverse 14

Refund given as a seller - reversed by Trust and Safety

RefundFromAccountReverse 15

Refund received as a buyer - reversed by Trust and Safety

AdminCredit 16

Ping credit added to account

TopUp 17

Top up Ping account

PurchaseAndTopup 18

Purchase and top up

RefundFromAccountRelease 19

Refund received as a buyer - transferred to balance by admin

WithdrawalRelease 20

Ping balance transfer out released

PurchaseReverseRelease 21

Purchase made as a buyer reversed and released

SettlementReverse 22

Settlement reversed

Dishonour 23

Dishonour

PurchaseCancelledUnclaimed 24

Purchase cancelled and unclaimed

RefundRetry 25

Refund retry

RefundUnclaimed 26

Refund unclaimed

PurchaseCancelledRetry 27

Purchase cancelled and retry

TopUpRelease 28

Top up release

PurchaseAndTopupRelease 29

Purchase and top up release

TopUpReverse 30

Top up Ping account reversed by Trust and Safety

PurchaseAndTopupReverse 31

Purchase and top up reversed by Trust and Safety

TopUpCancelledRetry 32

Top up cancelled retry

PurchaseAndTopUpCancelledRetry 33

Purchase and top up cancelled retry

TopUpReverseRelease 34

Top up Ping account reversed and released by Trust and Safety

PurchaseAndTopupReverseRelease 35

Purchase and top up reversed and released by Trust and Safety

TopUpReverseUnclaimed 36

Top up Ping account reversed and moved to unclaimed by Trust and Safety

PurchaseAndTopupReverseUnclaimed 37

Purchase and top up reversed and moved to unclaimed by Trust and Safety

CartSaleRelease 38

Cart sale release

Chargeback 39

Chargeback

PurchaseHold 40

Purchase on hold

TopUpHold 41

Top up on holds

PurchaseAndTopUpHold 42

Purchase and top up on hold

TradeMeAccountTopUp 43

Trade Me account top up

FeeRefund 44

Fee refund

TransactionDate DateTime

Date transaction was made in UTC time zone

TransactionParts Collection of <TransactionPart> or null

The transaction parts.

TransactionPartType Enumeration

Type of the Transaction part.

RefundToBalance 0

Refund to Ping balance

RefundToCard 1

Refund to credit/debit card

RefundToBankAccount 2

Refund to bank account

PingBalanceTopUp 3

Ping balance top up

PaymentFromBalance 4

Payment from Ping balance

PaymentFromCard 5

Payment from credit/debit card

PaymentFromBankAccount 6

Payment from bank account

Purchase 7

A purchased or sold item

LoyaltySubscriptionPurchase 8

A loyalty subscription purchase

PaymentFromLoyalty 9

Payment from loyalty

RefundToLoyalty 10

Refund to loyalty

PaymentFromOpenBank 11

Payment from open bank

Title String or null

Title of the Transaction part.

Amount Number

Amount of the Transaction part.

GstCollected Number or null

GST Collected from this transaction part.

ReferenceNumber String or null

The transaction part's reference number for correlation across systems and bank account and credit card statements. Purchase references begin with "P", Withdrawals begin with "W", Top-ups begin "TU", Refunds begin with "R", Peer to Peer and Donations with "Q"

Sku String or null

Sku of the Transaction part if its a purchase.

FundSources <FundSources> or null

Sources of fund used in a transaction.

Deprecated - use PaymentFrom instead of FundSources

AvailableBalance Number or null

The current available ping balance for use in funding a purchase.

FundSources Collection of <FundSource> or null

The collection of credit/debit card or bank account funding sources

Type Enumeration

The type of fund source. If the type is unrecognised, the API client should ignore this fund source and move on to the next one.

CreditCard 1

The fund source is a credit/debit card.

BankAccount 2

The fund source is a bank account.

PingBalance 3

The fund source is the Ping balance. Cannot be used in a purchase or top up. In a purchase use UseBalance = true instead.

TmLoyalty 4

The fund source is the Loyalty Subscription.

OpenBank 5

The fund source is Open Banking.

FundSourceId Long Integer

A unique ID that can be passed to the purchase API to identify the fund source to use.

MaskedAccountNumber String or null

A string containing the card or bank account number, with most of the digits blacked out for privacy reasons (e.g. "**** **** **** 1234" for a CC or "12 3456 ****789 00" for a bank account).

Label String or null

The user-provided label, if the user entered one for this fund source, or a generic label like "Visa credit card" otherwise.

Logo String or null

The URL to the card or bank logo. API clients should not assume any fixed dimensions, but instead scale the image to fit the space available. Logos are likely to be either square or wider than they are tall.

VerificationStatus Enumeration or null

The verification status of a bank account. Not applicable for credit/debit card fund sources.

Active 0

Represents an active bank account

Disabled 1

Represents a disabled bank account

Enabled 2

Represents a bank account that had not been verified and does not need to be verified. If you are checking if enabled, please also check for verified, as they are both statuses that allows a bank account to be used.

Verified 3

Represents a verified bank account. This is the same as enabled, but with a past verification taking place. If you are checking if verified, please also check for enabled, as they are both statuses that allows a bank account to be used.

Historical 4

Represents an historical bank account

VerificationRequired 5

Represents a bank account that needs verification.

Amount Number or null

Amount taken from the fund source.

VerificationCodeCreationDate DateTime or null

The date of the last sent verification code or null if a verification code has not been sent. This will be null if either no verification is required(see Status) or the batch payment process that includes the verification code for this fund source has not yet run(currently once per business day).

PaymentFrom Collection of <FundSource> or null

Fund sources the payment was made from

(This type has already been defined)
FundDestinations <FundDestinations> or null

Destination of fund going out of the Ping account.

Deprecated - use PaymentTo instead of FundDestinations

Amount Number or null

The current available ping balance for use in funding a purchase.

FundDestinations Collection of <FundDestination> or null

The collection of credit/debit card or bank account fund destinations.

BankAccountId Integer

Id used to identify the bank account

MaskedAccountNumber String or null

Masked account number eg. "12 3456 ****789 00"

Status Enumeration

The bank account status

Active 0

Represents an active bank account

Disabled 1

Represents a disabled bank account

Enabled 2

Represents a bank account that had not been verified and does not need to be verified. If you are checking if enabled, please also check for verified, as they are both statuses that allows a bank account to be used.

Verified 3

Represents a verified bank account. This is the same as enabled, but with a past verification taking place. If you are checking if verified, please also check for enabled, as they are both statuses that allows a bank account to be used.

Historical 4

Represents an historical bank account

VerificationRequired 5

Represents a bank account that needs verification.

Label String or null

Personal label to identify the account

Logo String or null

Personal label to identify the account

SortOrder Integer or null

the order of the account, 0 being the preferential account

Amount Number or null

Amount added to the fund destination.

VerificationCodeCreationDate DateTime or null

The date of the last sent verification code or null if a verification code has not been sent. This will be null if either no verification is required(see Status) or the batch payment process that includes the verification code for this fund source has not yet run(currently once per business day).

PaymentTo Collection of <FundSource> or null

Fund sources the payment was made to

(This type has already been defined)
Amount Number or null

Money either credited/deducted from the Ping account.

Balance Number

Available balance for the Ping account at the end of the transaction.

Fees Number or null

Total of all Fee amounts in the transaction parts.

Gst Number or null

Total of all Fee amounts in the transaction parts.

Title String or null

The action causing a balance change or the listing title for purchases and sales. Refer to transaction parts for multi item purchase or topups

ListingId String or null

The listing id. Refer transaction parts ListingId cart and purchase + topups

ReferenceNumber String or null

The transaction's reference number for correlation across systems and bank account and credit card statements. Purchase references begin with "P", Cart purchases begin with "C", Withdrawals begin with "W", Top-ups begin "TU", Refunds begin with "R", Peer to Peer and Donations with "Q"

Sku String or null

Stock Keeping Unit (SKU) of the listing

Subtitle String or null

Additional information regarding the transaction's action

IsCart Boolean

Determines whether or not this transaction was used to complete a cart purchase.

Example XML Response (switch to JSON)

<BalanceLedgerResponse xmlns="http://api.trademe.co.nz/v1">
  <TotalCount>123</TotalCount>
  <Page>123</Page>
  <PageSize>123</PageSize>
  <List>
    <Transaction>
      <TransactionId>123</TransactionId>
      <TransactionType>Purchase</TransactionType>
      <TransactionDate>2018-01-01T00:00:00Z</TransactionDate>
      <TransactionParts>
        <TransactionPart>
          <TransactionPartType>RefundToBalance</TransactionPartType>
          <Title>ABC</Title>
          <Amount>123.0</Amount>
          <GstCollected>123.0</GstCollected>
          <ReferenceNumber>ABC</ReferenceNumber>
          <Sku>ABC</Sku>
        </TransactionPart>
        <TransactionPart>
          <TransactionPartType>RefundToBalance</TransactionPartType>
          <Title>ABC</Title>
          <Amount>123.0</Amount>
          <GstCollected>123.0</GstCollected>
          <ReferenceNumber>ABC</ReferenceNumber>
          <Sku>ABC</Sku>
        </TransactionPart>
      </TransactionParts>
      <FundSources>
        <AvailableBalance>123.0</AvailableBalance>
        <FundSources>
          <FundSource>
            <Type>CreditCard</Type>
            <FundSourceId>123</FundSourceId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <VerificationStatus>Active</VerificationStatus>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundSource>
          <FundSource>
            <Type>CreditCard</Type>
            <FundSourceId>123</FundSourceId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <VerificationStatus>Active</VerificationStatus>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundSource>
        </FundSources>
      </FundSources>
      <PaymentFrom>
        <FundSource />
        <FundSource />
      </PaymentFrom>
      <FundDestinations>
        <Amount>123.0</Amount>
        <FundDestinations>
          <FundDestination>
            <BankAccountId>123</BankAccountId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Status>Active</Status>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <SortOrder>123</SortOrder>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundDestination>
          <FundDestination>
            <BankAccountId>123</BankAccountId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Status>Active</Status>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <SortOrder>123</SortOrder>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundDestination>
        </FundDestinations>
      </FundDestinations>
      <PaymentTo>
        <FundSource />
        <FundSource />
      </PaymentTo>
      <Amount>123.0</Amount>
      <Balance>123.0</Balance>
      <Fees>123.0</Fees>
      <Gst>123.0</Gst>
      <Title>ABC</Title>
      <ListingId>ABC</ListingId>
      <ReferenceNumber>ABC</ReferenceNumber>
      <Sku>ABC</Sku>
      <Subtitle>ABC</Subtitle>
      <IsCart>false</IsCart>
    </Transaction>
    <Transaction>
      <TransactionId>123</TransactionId>
      <TransactionType>Purchase</TransactionType>
      <TransactionDate>2018-01-01T00:00:00Z</TransactionDate>
      <TransactionParts>
        <TransactionPart>
          <TransactionPartType>RefundToBalance</TransactionPartType>
          <Title>ABC</Title>
          <Amount>123.0</Amount>
          <GstCollected>123.0</GstCollected>
          <ReferenceNumber>ABC</ReferenceNumber>
          <Sku>ABC</Sku>
        </TransactionPart>
        <TransactionPart>
          <TransactionPartType>RefundToBalance</TransactionPartType>
          <Title>ABC</Title>
          <Amount>123.0</Amount>
          <GstCollected>123.0</GstCollected>
          <ReferenceNumber>ABC</ReferenceNumber>
          <Sku>ABC</Sku>
        </TransactionPart>
      </TransactionParts>
      <FundSources>
        <AvailableBalance>123.0</AvailableBalance>
        <FundSources>
          <FundSource>
            <Type>CreditCard</Type>
            <FundSourceId>123</FundSourceId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <VerificationStatus>Active</VerificationStatus>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundSource>
          <FundSource>
            <Type>CreditCard</Type>
            <FundSourceId>123</FundSourceId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <VerificationStatus>Active</VerificationStatus>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundSource>
        </FundSources>
      </FundSources>
      <PaymentFrom>
        <FundSource />
        <FundSource />
      </PaymentFrom>
      <FundDestinations>
        <Amount>123.0</Amount>
        <FundDestinations>
          <FundDestination>
            <BankAccountId>123</BankAccountId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Status>Active</Status>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <SortOrder>123</SortOrder>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundDestination>
          <FundDestination>
            <BankAccountId>123</BankAccountId>
            <MaskedAccountNumber>ABC</MaskedAccountNumber>
            <Status>Active</Status>
            <Label>ABC</Label>
            <Logo>ABC</Logo>
            <SortOrder>123</SortOrder>
            <Amount>123.0</Amount>
            <VerificationCodeCreationDate>2018-01-01T00:00:00Z</VerificationCodeCreationDate>
          </FundDestination>
        </FundDestinations>
      </FundDestinations>
      <PaymentTo>
        <FundSource />
        <FundSource />
      </PaymentTo>
      <Amount>123.0</Amount>
      <Balance>123.0</Balance>
      <Fees>123.0</Fees>
      <Gst>123.0</Gst>
      <Title>ABC</Title>
      <ListingId>ABC</ListingId>
      <ReferenceNumber>ABC</ReferenceNumber>
      <Sku>ABC</Sku>
      <Subtitle>ABC</Subtitle>
      <IsCart>false</IsCart>
    </Transaction>
  </List>
</BalanceLedgerResponse>

Example JSON Response (switch to XML)

{
  "TotalCount": 123,
  "Page": 123,
  "PageSize": 123,
  "List": [
    {
      "TransactionId": 123,
      "TransactionType": 0,
      "TransactionDate": "\/Date(1514764800)\/",
      "TransactionParts": [
        {
          "TransactionPartType": 0,
          "Title": "ABC",
          "Amount": 123.0,
          "GstCollected": 123.0,
          "ReferenceNumber": "ABC",
          "Sku": "ABC"
        },
        {
          "TransactionPartType": 0,
          "Title": "ABC",
          "Amount": 123.0,
          "GstCollected": 123.0,
          "ReferenceNumber": "ABC",
          "Sku": "ABC"
        }
      ],
      "FundSources": {
        "AvailableBalance": 123.0,
        "FundSources": [
          {
            "Type": 1,
            "FundSourceId": 123,
            "MaskedAccountNumber": "ABC",
            "Label": "ABC",
            "Logo": "ABC",
            "VerificationStatus": 0,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          },
          {
            "Type": 1,
            "FundSourceId": 123,
            "MaskedAccountNumber": "ABC",
            "Label": "ABC",
            "Logo": "ABC",
            "VerificationStatus": 0,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          }
        ]
      },
      "PaymentFrom": [
        {
        },
        {
        }
      ],
      "FundDestinations": {
        "Amount": 123.0,
        "FundDestinations": [
          {
            "BankAccountId": 123,
            "MaskedAccountNumber": "ABC",
            "Status": 0,
            "Label": "ABC",
            "Logo": "ABC",
            "SortOrder": 123,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          },
          {
            "BankAccountId": 123,
            "MaskedAccountNumber": "ABC",
            "Status": 0,
            "Label": "ABC",
            "Logo": "ABC",
            "SortOrder": 123,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          }
        ]
      },
      "PaymentTo": [
        {
        },
        {
        }
      ],
      "Amount": 123.0,
      "Balance": 123.0,
      "Fees": 123.0,
      "Gst": 123.0,
      "Title": "ABC",
      "ListingId": "ABC",
      "ReferenceNumber": "ABC",
      "Sku": "ABC",
      "Subtitle": "ABC",
      "IsCart": false
    },
    {
      "TransactionId": 123,
      "TransactionType": 0,
      "TransactionDate": "\/Date(1514764800)\/",
      "TransactionParts": [
        {
          "TransactionPartType": 0,
          "Title": "ABC",
          "Amount": 123.0,
          "GstCollected": 123.0,
          "ReferenceNumber": "ABC",
          "Sku": "ABC"
        },
        {
          "TransactionPartType": 0,
          "Title": "ABC",
          "Amount": 123.0,
          "GstCollected": 123.0,
          "ReferenceNumber": "ABC",
          "Sku": "ABC"
        }
      ],
      "FundSources": {
        "AvailableBalance": 123.0,
        "FundSources": [
          {
            "Type": 1,
            "FundSourceId": 123,
            "MaskedAccountNumber": "ABC",
            "Label": "ABC",
            "Logo": "ABC",
            "VerificationStatus": 0,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          },
          {
            "Type": 1,
            "FundSourceId": 123,
            "MaskedAccountNumber": "ABC",
            "Label": "ABC",
            "Logo": "ABC",
            "VerificationStatus": 0,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          }
        ]
      },
      "PaymentFrom": [
        {
        },
        {
        }
      ],
      "FundDestinations": {
        "Amount": 123.0,
        "FundDestinations": [
          {
            "BankAccountId": 123,
            "MaskedAccountNumber": "ABC",
            "Status": 0,
            "Label": "ABC",
            "Logo": "ABC",
            "SortOrder": 123,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          },
          {
            "BankAccountId": 123,
            "MaskedAccountNumber": "ABC",
            "Status": 0,
            "Label": "ABC",
            "Logo": "ABC",
            "SortOrder": 123,
            "Amount": 123.0,
            "VerificationCodeCreationDate": "\/Date(1514764800)\/"
          }
        ]
      },
      "PaymentTo": [
        {
        },
        {
        }
      ],
      "Amount": 123.0,
      "Balance": 123.0,
      "Fees": 123.0,
      "Gst": 123.0,
      "Title": "ABC",
      "ListingId": "ABC",
      "ReferenceNumber": "ABC",
      "Sku": "ABC",
      "Subtitle": "ABC",
      "IsCart": false
    }
  ]
}