Displaying transactions

As described in the getting started guide, Yordex has both payments and orders:

Payments have information provided by the banking partner only
Orders have additional information provided by yourself or Yordex such as invoices, receipts, tax codes, cost allocations etc.

You can choose to display payments, orders or both in your app. This page describes how to do it:

Transactions can also be viewed in our mobile app or in the orders and statement sections of our web app.

Getting payments for a card

Getting a list of all payments for a card is done as follows:

curl {baseURL}/reports/yordexpay?cardId=:card_id
-H "Authorization:your-api-key"  
-X GET

The following search parameters can be provided:

Required

cardId=card-id: will only return transactions for a specific card. This id is returned when getting cards
currency: the currency of the card being requested. In 3 letter ISO 4217 format (e.g. GBP)

Optional

startDate, endDate: to specify the date range; for example, '&startDate=2021-10-01&endDate=2021-10-31' will return a statement for October
includeAccountTopUps=true: will include (true) or exclude (false) bank transfers into and out of the account
includeCardTransactions=true: will include (true) or exclude (false) card payments
includeTopUps=true: will include (true) or exclude (false) card top ups
transactionStatus: will only return transactions with the specified status (SETTLED, PENDING, DECLINED, REVERSED). Default value = PENDING,SETTLED
Pagination filters: as described here

The response will look as follows:

{
  "content": [
    {
      // transaction specific fields
      "transactionId": ":transaction_id",
      "currency": "USD",
      "debitCredit": "DEBIT",
      "amountInCents": 5000,
      "date": "2023-01-27",
      "settlementDate": "2023-01-28",
      "description": "AMAZON US",
      "status": "SETTLED",

      // fields from the account this transction is linked to
      "yordexPayAccountId": ":yordex_pay_account_id",
      "balanceInCents": -644800,
      "transactionNumber":101,
      "transactionSource": "CARD",

      // fields from the card this transction is linked to
      "cardId": ":card_id",
      "cardHolder": "[email protected]",
      "cardHolderName": "Peter Parker",

      // merchant fields 
      "mid": "mechant-id",
      "mcc": "accounting_bookkeeping_services",

      // (optional) fields from the order this transction is auto-reconciled with
      "orderId": ":order_id",
      "eventId": ":event_id",
      "orderStatus": "NOT_APPROVED",
      "eventStatus": "NOT_STARTED",
      "sellerId": ":seller_id",
      "sellerCompanyTradingName": "Peter Parket"
    }
  ]
}

debitCredit indicates if it was a payment (DEBIT) or refund (CREDIT).

The status indicates the status. A transaction is first PENDING before it becomes SETTLED. This settlement happens on the settlementDate. It can take 1 or 2 days for the transaction to be settled. If the transaction is DECLINED you will find the decline reason in the description field.

The balanceInCents is the balance of the account after this transaction. It will only be updated once the transaction is SETTLED. The transactionNumber is a consecutive number that you should use to order the transactions on a statement to make sure these balances display correctly.

The transactionSource indicates if it was a card payment (CARD) or bank transfer (ACCOUNT).

mid stands for Merchant Identifier and is a unique identifier for this merchant. This field is defined by VISA or MASTERCARD but it is not always provided. The mcc stands for Merchant Category Code and is a unique identifier for the type of merchant this is. This field is again defined by VISA or MASTERCARD. The mccDescription provides a human readable description of the mcc.

All other fields are described in the API reference.

Getting payments for an account

Getting a list of all payments for a card is done as follows:

curl {baseURL}/reports/yordexpay?accountId=:accountId
-H "Authorization:your-api-key"  
-X GET

The following search parameters can be provided:

Required

accountId=accountId:will return transactions for all cards within an account. This id is returned when getting accounts
currency: the currency of the account being requested. In 3 letter ISO 4217 format (e.g. GBP)

Optional
startDate, endDate: to specify the date range; for example, '&startDate=2021-10-01&endDate=2021-10-31' will return a statement for October
includeAccountTopUps=true: will include (true) or exclude (false) bank transfers into and out of the account
includeCardTransactions=true: will include (true) or exclude (false) card payments
includeTopUps=true: will include (true) or exclude (false) card top ups
transactionStatus: will only return transactions with the specified status (SETTLED, PENDING, DECLINED, REVERSED). Default value = PENDING,SETTLED
Pagination filters: as described here

The response will contain the same fields as when requesting a card transaction list.

Getting orders

Getting a single order can be done like this:

curl https://api.yordex.com/v1/aggregate/orders/:order-id  
-H "Authorization:your-api-key"  
-X GET

The response is as follows:

{
  "id" : ":order-id",
  "buyerId" : "your-trader-id",
  "buyerCompanyTradingName": "Buyer Name",
  "sellerId" : "other-trader-id",
  "sellerCompanyTradingName": "Seller Name",
  "description": "My order",
  "orderAmountInCents": 100000,
  "orderCurrency": "USD",
  "status": "NOT_APPROVED",
  "events": [
    {
      "id": "event-id-1",
      "pctToBePaid": 100,
      "eventName": "Order approved",
      "paymentName": "Full payment",
      "eventNumber": 1,
      "amountToBePaidInCents": 30000,
      "status": "NOT_STARTED",
      "confirmers": [
         "BUYER"
      ],
      "confirmed": false,
      "documents": [
        {
            "id": "document-id",
            "location": "{baseURL}/documents/download/document-id",
            "fileName": "invoice.pdf",
            "type": "INVOICE",
            "documentDate": "2021-10-03",
            "customerDocumentId": "INV-001"
        }
      ]
    }
  ]
}

Each of these fields is described in the API reference.

Most orders will only have one event, but some orders will have multiple events. For example, subscriptions are represented by a single order with one event for each billing period, e.g. one event per month and partially received orders are represented by a single order with one event for each invoice for partial delivery. See here for a more detailed explanation of events.

PDF images of receipts and invoices are stored as documents. The best way to retrieve receipts is by going to the spend page in the web app, choosing "Export" and then choosing "Export invoice files". You can also download them using the location URL provided in the response.

Getting a list of all your orders is done as follows:

curl {baseURL}/aggregate/orders?orderStatus=APPROVED&eventStatus=PAYMENT_DUE&buyerUserId=user-id&buyerTagValues=EXPENSE&q=abc 
-H "Authorization:your-api-key"  
-X GET

The following parameters can be used in combination:

orderStatus filters on order status, e.g. "?orderStatus=APPROVED" returns all approved orders
eventStatus filters on order status, e.g. "?eventStatus=FOR_CONFIRMATION" returns all orders where at least one of the events is FOR_CONFIRMATION
userId filters on orders where this user is the buyerUser or sellerUser
buyerTagValues filter, e.g. "?buyerTagValues=EXPENSE" returns all expenses
q: specifies a search query. The orderId, description, buyerOrderReference, sellerOrderReference, companyTradingName, buyerUserEmail and buyerCostAllocation.budgetName will be searched for the specified string

All parameters can be combined to return the orders you are looking for.