Back to top

 

Merchant transactions

Transaction history

Transaction history
GET/v0.1/me/transactions/history

Returns a paginated list of transaction-related events of the currently authenticated SumUp account. A transation-related event is either a payment, refund or charge back. Optional filtering parameters provide fine-grained control over the returned data. The result set has an optional “next” attribute, which can be used to fetch subsequent pages.

Required scope(s): transactions.history

Resource URL

GET https://api.sumup.com/v0.1/me/transactions/history
Parameters
HideShow
order
string (optional) 

Ordering of results by timestamp. Possible values: ‘ascending’ (default), ‘descending’

limit
number (optional) 

Maximum number of results per page

users[]
array (optional) 

Filter by user email

geo_coordinates
string (optional) 

Filter by geo coordinates: use CSVs of southwest_lng, southwest_lat, northeast_lng, northeast_lat

readers[]
array (optional) 

Filter by reader serial number

statuses[]
array (optional) 

Filter by status. Possible values: SUCCESSFUL, CANCELLED, FAILED

payment_types[]
array (optional) 

Filter by payment type. Possible values: CASH, POS, ECOM, BITCOIN, BALANCE

types[]
array (optional) 

Filter by event type. Possible values: PAYMENT, REFUND, CHARGE_BACK

changes_since
string (optional) 

Return only transactions that have been updated after the given timestamp. Format: ISO8601 (xmlschema)

newest_time
string (optional) 

Return only transactions that occurred before the given timestamp. Format: ISO8601 (xmlschema)

newest_ref
string (optional) 

Return only transactions that occurred after the given event ID

oldest_time
string (optional) 

Return only transactions that occurred after the given timestamp. Format: ISO8601 (xmlschema)

oldest_ref
string (optional) 

Return only transactions that occurred before the given event ID

Response  200
HideShow
Body
{
  "items": [
    {
      "id": "...",
      "transaction_id: ... (string, optional) - Associated SumUp transaction ID. The value of this and the \"id\" fields may be equal. Multiple events, associated to the same transaction will have the same transaction_id, e.g. when a PAYMENT event is later followed by a REFUND": "Hello, world!",
      "user": "...",
      "type": "...",
      "status": "...",
      "timestamp": "...",
      "currency": "...",
      "amount": 1,
      "transaction_code": "...",
      "product_summary": "...",
      "installments_count": 1,
      "payment_type": "...",
      "card_type: ... (string, optional) - Card type. Possible values: AMEX, CUP, DINERS, DISCOVER, ELV, JCB, MAESTRO, MASTERCARD, VISA, VISA_ELECTRON, VISA_VPAY, UNKNOWN": "Hello, world!",
      "payouts_total": 1,
      "payouts_received": 1,
      "payout_date: ... (string, optional) - Payout date. Omitted when the payouts_total > 1. Available for PAYMENT events only.": "Hello, world!",
      "payout_plan": "...",
      "payout_type: ... (string, optional) - Payout type -- indicates how the amount was (will be) paid out to the merchant account. Possible values: BANK_ACCOUNT, PREPAID_CARD, BALANCE. Available for PAYMENT events only": "Hello, world!"
    }
  ],
  "links": [
    {
      "rel": "...",
      "href": "...",
      "type": "..."
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique SumUp event ID"
          },
          "transaction_id: ... (string, optional) - Associated SumUp transaction ID. The value of this and the \"id\" fields may be equal. Multiple events, associated to the same transaction will have the same transaction_id, e.g. when a PAYMENT event is later followed by a REFUND": {
            "type": "string"
          },
          "user": {
            "type": "string",
            "description": "Email of the SumUp user that accepted payment"
          },
          "type": {
            "type": "string",
            "description": "Type. Possible values: PAYMENT, REFUND, CHARGE_BACK"
          },
          "status": {
            "type": "string",
            "description": "Current status. Possible values: SUCCESSFUL, CANCELLED, FAILED"
          },
          "timestamp": {
            "type": "string",
            "description": "Timestamp at which the event occurred"
          },
          "currency": {
            "type": "string",
            "description": "Currency alpha-3 code"
          },
          "amount": {
            "type": "number",
            "description": "Total event amount"
          },
          "transaction_code": {
            "type": "string",
            "description": "Short representation of the SumUp transaction ID. Useful for presenting it to customers, e.g. on receipts or reports"
          },
          "product_summary": {
            "type": "string",
            "description": "A user-defined short description of the transaction"
          },
          "installments_count": {
            "type": "number",
            "description": "Number of installments the transactions was made. Value is always 1, except for merchants in Brazil"
          },
          "payment_type": {
            "type": "string",
            "description": "Payment type. Possible values: CASH, POS, ECOM, BITCOIN, BALANCE"
          },
          "card_type: ... (string, optional) - Card type. Possible values: AMEX, CUP, DINERS, DISCOVER, ELV, JCB, MAESTRO, MASTERCARD, VISA, VISA_ELECTRON, VISA_VPAY, UNKNOWN": {
            "type": "string"
          },
          "payouts_total": {
            "type": "number",
            "description": "Indicates the total number of payouts. Value is always 1, except for merchants in Brazil. Available for PAYMENT events only"
          },
          "payouts_received": {
            "type": "number",
            "description": "Number of payouts that were paid to the merchant. Available for PAYMENT events only"
          },
          "payout_date: ... (string, optional) - Payout date. Omitted when the payouts_total > 1. Available for PAYMENT events only.": {
            "type": "string"
          },
          "payout_plan": {
            "type": "string",
            "description": "Payout plan at the time the transaction was made. Available for PAYMENT events only"
          },
          "payout_type: ... (string, optional) - Payout type -- indicates how the amount was (will be) paid out to the merchant account. Possible values: BANK_ACCOUNT, PREPAID_CARD, BALANCE. Available for PAYMENT events only": {
            "type": "string"
          }
        }
      },
      "description": "Collection of history items"
    },
    "links": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rel": {
            "type": "string",
            "description": "Relation"
          },
          "href": {
            "type": "string",
            "description": "Location"
          },
          "type": {
            "type": "string",
            "description": "Mime type"
          }
        }
      },
      "description": "Collection of links.Currently next page link"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Transaction details

Transaction details
GET/v0.1/me/transactions

Finds a single transaction based on the given parameters and returns detailed information for that transaction

Required scope(s): transactions.history

Resource URL

GET https://api.sumup.com/v0.1/me/transactions
Parameters
HideShow
id
string (optional) 

Unique SumUp transaction ID

internal_id
string (optional) 

Unique SumUp internal transaction ID

code
string (optional) 

Short representation of the SumUp transaction ID

foreign_transaction_id
string (optional) 

External (foreign) transaction ID. Present only if such ID was provided during transaction creation

client_transaction_id
string (optional) 

Client transaction id. Similar to the foreign_transaction_id, but is always present

Response  200
HideShow
Body
{
  "id": "...",
  "transaction_code": "...",
  "foreign_transaction_id": "...",
  "merchant_code": "...",
  "username": "...",
  "amount": 1,
  "vat_amount": 1,
  "tip_amount": 1,
  "currency": "...",
  "timestamp": "...",
  "lat": 1,
  "lon": 1,
  "horizontal_accuracy": 1,
  "status": "...",
  "payment_type": "...",
  "entry_mode": "...",
  "verification_method": "...",
  "card": {
    "last_4_digits": "...",
    "type": "..."
  },
  "elv_account": {
    "sort_code": "...",
    "last_4_digits": "..."
  },
  "product_summary": "...",
  "local_time": "...",
  "payout_date": "...",
  "payout_plan": "...",
  "payout_type": "...",
  "installments_count": 1,
  "process_as": "...",
  "products": {
    "name": "...",
    "price": 1,
    "vat_rate": 1,
    "single_vat_amount": 1,
    "price_with_vat": 1,
    "vat_amount": 1,
    "quantity": 1,
    "total_price": 1,
    "total_with_vat": 1
  },
  "transaction_events": {
    "id": 1,
    "event_type: ... (string, optional) - Type of the transaction event. Possible values: PAYOUT, CHARGE_BACK, REFUND": "Hello, world!",
    "status": "...",
    "amount": 1,
    "due_date": "...",
    "date": "...",
    "installment_number": 1,
    "timestamp": "..."
  },
  "simple_status: CANCEL_FAILED|CANCELLED|CHARGEBACK|FAILED|REFUND_FAILED|REFUNDED|SUCCESSFUL(string, optional) - Simple status generated from processing status and latest transaction state - Possible values CANCEL_FAILED,CANCELLED,CHARGEBACK,FAILED,REFUND_FAILED,REFUNDED,SUCCESSFUL": "Hello, world!",
  "links": {
    "rel": "...",
    "href": "...",
    "type": "..."
  },
  "events": {
    "id": 1,
    "transaction_id": "...",
    "type": "...",
    "status": "...",
    "amount": 1,
    "timestamp": "...",
    "fee_amount": 1
  },
  "payouts_received": 1,
  "payouts_total": 1,
  "location": {
    "lat": 1,
    "lon": 1,
    "horizontal_accuracy": 1
  },
  "internal_id": 1
}
Schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Transaction id"
    },
    "transaction_code": {
      "type": "string",
      "description": "Transaction code"
    },
    "foreign_transaction_id": {
      "type": "string",
      "description": "Foreign transaction id (passed by clients)"
    },
    "merchant_code": {
      "type": "string",
      "description": "Merchant code"
    },
    "username": {
      "type": "string",
      "description": "Username of the user who made the transactions"
    },
    "amount": {
      "type": "number",
      "description": "Transaction amount"
    },
    "vat_amount": {
      "type": "number",
      "description": "Transaction VAT amount"
    },
    "tip_amount": {
      "type": "number",
      "description": "Tip amount (included in transaction amount)"
    },
    "currency": {
      "type": "string",
      "description": "Transaction currency"
    },
    "timestamp": {
      "type": "string",
      "description": "Time created"
    },
    "lat": {
      "type": "number",
      "description": "Latitude"
    },
    "lon": {
      "type": "number",
      "description": "Longitude"
    },
    "horizontal_accuracy": {
      "type": "number",
      "description": "Position precision"
    },
    "status": {
      "type": "string",
      "description": "Transaction processing status"
    },
    "payment_type": {
      "type": "string",
      "description": "Transaction type"
    },
    "entry_mode": {
      "type": "string",
      "description": "Transaction entry mode"
    },
    "verification_method": {
      "type": "string",
      "description": "Cardholder verification method"
    },
    "card": {
      "type": "object",
      "properties": {
        "last_4_digits": {
          "type": "string",
          "description": "Card last 4 digits"
        },
        "type": {
          "type": "string",
          "description": "Card Scheme"
        }
      },
      "description": "Card information"
    },
    "elv_account": {
      "type": "object",
      "properties": {
        "sort_code": {
          "type": "string",
          "description": "Elv card sort code"
        },
        "last_4_digits": {
          "type": "string",
          "description": "Elv card account number last 4 digits"
        }
      },
      "description": "Elv bank account"
    },
    "product_summary": {
      "type": "string",
      "description": "Product summary"
    },
    "local_time": {
      "type": "string",
      "description": "Creation time in the timezone of the device on which the transaction was made"
    },
    "payout_date": {
      "type": "string",
      "description": "The date of the payout"
    },
    "payout_plan": {
      "type": "string",
      "description": "Payout plan at the time the transaction was made"
    },
    "payout_type": {
      "type": "string",
      "description": "Payout type of the most recent paid-out for this transaction"
    },
    "installments_count": {
      "type": "number",
      "description": "Number of installments"
    },
    "process_as": {
      "type": "string",
      "description": "Debit/Credit"
    },
    "products": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Product name"
        },
        "price": {
          "type": "number",
          "description": "Product price"
        },
        "vat_rate": {
          "type": "number",
          "description": "undefined"
        },
        "single_vat_amount": {
          "type": "number",
          "description": "undefined"
        },
        "price_with_vat": {
          "type": "number",
          "description": "Product price incl. VAT"
        },
        "vat_amount": {
          "type": "number",
          "description": "undefined"
        },
        "quantity": {
          "type": "number",
          "description": "Product quantity"
        },
        "total_price": {
          "type": "number",
          "description": "Quantity x product price"
        },
        "total_with_vat": {
          "type": "number",
          "description": "Total price incl. VAT"
        }
      },
      "description": "Purchase products"
    },
    "transaction_events": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Event ID"
        },
        "event_type: ... (string, optional) - Type of the transaction event. Possible values: PAYOUT, CHARGE_BACK, REFUND": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "description": "Status of the event"
        },
        "amount": {
          "type": "number",
          "description": "Amount"
        },
        "due_date": {
          "type": "string",
          "description": "The date when the event is due to occur"
        },
        "date": {
          "type": "string",
          "description": "The date when this event occurred"
        },
        "installment_number": {
          "type": "number",
          "description": "The number of installment that was payed out in case of a PAYOUT event"
        },
        "timestamp": {
          "type": "string",
          "description": "Time created"
        }
      },
      "description": "A list of transaction events such as payouts, refunds and chargebacks"
    },
    "simple_status: CANCEL_FAILED|CANCELLED|CHARGEBACK|FAILED|REFUND_FAILED|REFUNDED|SUCCESSFUL(string, optional) - Simple status generated from processing status and latest transaction state - Possible values CANCEL_FAILED,CANCELLED,CHARGEBACK,FAILED,REFUND_FAILED,REFUNDED,SUCCESSFUL": {
      "type": "string"
    },
    "links": {
      "type": "object",
      "properties": {
        "rel": {
          "type": "string",
          "description": "Relation"
        },
        "href": {
          "type": "string",
          "description": "Location"
        },
        "type": {
          "type": "string",
          "description": "Mime type"
        }
      },
      "description": "A list with links to related resources"
    },
    "events": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Event ID"
        },
        "transaction_id": {
          "type": "string",
          "description": "Parent transaction ID"
        },
        "type": {
          "type": "string",
          "description": "Type of the transaction event. Possible values: PAYOUT, CHARGE_BACK, REFUND"
        },
        "status": {
          "type": "string",
          "description": "Status of the event"
        },
        "amount": {
          "type": "number",
          "description": "Amount"
        },
        "timestamp": {
          "type": "string",
          "description": "Time created"
        },
        "fee_amount": {
          "type": "number",
          "description": "Fee amount"
        }
      },
      "description": "A list with transaction events"
    },
    "payouts_received": {
      "type": "number",
      "description": "Number of payouts that were actually paid out (excludes partial chargeback deductions)"
    },
    "payouts_total": {
      "type": "number",
      "description": "Total number of payouts in which the transaction is (to) be paid out"
    },
    "location": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "description": "undefined"
        },
        "lon": {
          "type": "number",
          "description": "undefined"
        },
        "horizontal_accuracy": {
          "type": "number",
          "description": "undefined"
        }
      },
      "description": "Location information"
    },
    "internal_id": {
      "type": "number",
      "description": "The internal transaction ID"
    }
  },
  "description": "<p>&nbsp;</p>\n",
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Merchant refunds

Refund transaction

Refund transaction
POST/v0.1/me/refund/:server_transaction_id

Refund a transaction

Resource URL

POST https://api.sumup.com/v0.1/me/refund/:server_transaction_id
Parameters
HideShow
server_transaction_id
string (required) 

SumUp transaction ID

Response  204
HideShow
Body
Processing completed successfully
Response  409
HideShow
Body
The transaction is not refundable in its current state