SUsumup
Transactions

Retrieve a transaction

Changed on

Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and one of following parameters is required:

  • id
  • transaction_code
  • foreign_transaction_id
  • client_transaction_id
get/v2.1/merchants/{merchant_code}/transactions

Request

  • Base URL
    https://api.sumup.com
  • URL
    https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://api.sumup.com/authorize
      Token URL: https://api.sumup.com/token scopes: transactions.history, transactions.read

Path parameters

merchant_codestring required
Example:MH4H92C7

Short unique identifier for the merchant.

Query parameters

idstring
Example:410fc44a-5956-44e1-b5cc-19c6f8d727a4

Retrieves the transaction resource with the specified transaction ID (the id parameter in the transaction resource).

transaction_codestring
Example:TEENSK4W2K

Retrieves the transaction resource with the specified transaction code.

foreign_transaction_idstring
Example:J13253253x1

External transaction identifier supplied by the client.

client_transaction_idstring
Example:urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2

Client-supplied identifier of the transaction.

Response

Returns the requested transaction resource.

idstring

Unique identifier of the transaction.

transaction_codestring

SumUp transaction code, for example TEENSK4W2K. Use it to look up the transaction with the transaction_code query parameter. This is separate from the transaction's id and the card issuer's auth_code.

amountnumber float

Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.

currency'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD'

Three-letter ISO 4217 currency code of the amount.

timestampstring date-time

The timestamp of when the transaction was created.

status'SUCCESSFUL' | 'CANCELLED' | 'FAILED' | 'PENDING' | 'REFUNDED'

Current status of the transaction.

  • PENDING: The transaction has been created but its final outcome is not known yet.
  • SUCCESSFUL: The transaction completed successfully.
  • CANCELLED: The transaction was cancelled or otherwise reversed before completion.
  • FAILED: The transaction attempt did not complete successfully.
  • REFUNDED: The transaction was refunded in full or in part.
payment_type'CASH' | 'POS' | 'ECOM' | 'RECURRING' | 'BITCOIN' | 'BALANCE' | 'MOTO' | 'BOLETO' | 'DIRECT_DEBIT' | 'APM' | 'UNKNOWN'

Payment category recorded on a transaction, for example POS for a point-of-sale card payment, ECOM for an online card payment, or RECURRING for a recurring card payment. These reporting values are separate from the lowercase payment_type values used to process checkouts.

installments_countinteger

Number of installments for a deferred payment.

merchant_codestring

Unique code of the registered merchant to whom the payment is made.

vat_amountnumber float

VAT included in the total transaction amount, in major units of the transaction's currency.

tip_amountnumber float

Tip included in the total transaction amount, in major units of the transaction's currency.

entry_mode'BOLETO' | 'SOFORT' | 'IDEAL' | 'BANCONTACT' | 'EPS' | 'MYBANK' | 'SATISPAY' | 'BLIK' | 'P24' | 'GIROPAY' | 'PIX' | 'QR_CODE_PIX' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'PAYPAL' | 'TWINT' | 'NONE' | 'CHIP' | 'MANUAL_ENTRY' | 'CUSTOMER_ENTRY' | 'MAGSTRIPE_FALLBACK' | 'MAGSTRIPE' | 'DIRECT_DEBIT' | 'CONTACTLESS' | 'MOTO' | 'CONTACTLESS_MAGSTRIPE' | 'N/A'

How the payment details were captured, for example CHIP or CONTACTLESS for card-present payments and CUSTOMER_ENTRY for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as APPLE_PAY or BLIK.

auth_codestring

Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

product_summarystring

Short description of the payment. The value is taken from the description property of the related checkout resource.

payouts_totalinteger

Total number of payouts to the registered user specified in the user property.

payouts_receivedinteger

Number of payouts that are made to the registered user specified in the user property.

payout_plan'SINGLE_PAYMENT' | 'TRUE_INSTALLMENT' | 'ACCELERATED_INSTALLMENT'

Payout plan of the registered user at the time when the transaction was made.

foreign_transaction_idstring

External transaction identifier supplied by the client.

client_transaction_idstring

Client-supplied identifier of the transaction.

usernamestring email

Email address of the registered user (merchant) to whom the payment is made.

fee_amountnumber

Total SumUp transaction fee in major units of the transaction's currency.

latnumber float

Latitude value from the coordinates of the payment location (as received from the payment terminal reader).

lonnumber float

Longitude value from the coordinates of the payment location (as received from the payment terminal reader).

horizontal_accuracynumber float

Indication of the precision of the geographical position received from the payment terminal.

merchant_idinteger

Internal SumUp identifier of the merchant.

simple_payment_type'CASH' | 'CC_SIGNATURE' | 'ELV' | 'ELV_WITHOUT_SIGNATURE' | 'CC_CUSTOMER_ENTERED' | 'MANUAL_ENTRY' | 'EMV' | 'RECURRING' | 'BALANCE' | 'MOTO' | 'BOLETO' | 'APM' | 'BITCOIN' | 'CARD'

Simple name of the payment type.

verification_method'none' | 'signature' | 'offline PIN' | 'online PIN' | 'offline PIN + signature' | 'na'

Verification method used for the transaction.

local_timestring date-time

Local timestamp of when the transaction was created.

payout_datestring date

The date of the payout.

payout_type'BANK_ACCOUNT' | 'PREPAID_CARD'

Payout type for the transaction.

process_as'CREDIT' | 'DEBIT'

Whether the transaction was processed as credit or debit.

simple_status'SUCCESSFUL' | 'PAID_OUT' | 'CANCEL_FAILED' | 'CANCELLED' | 'CHARGEBACK' | 'FAILED' | 'REFUND_FAILED' | 'REFUNDED' | 'NON_COLLECTION' | 'PENDING'

High-level status of the transaction from the merchant's perspective.

  • PENDING: The payment has been initiated and is still being processed. A final outcome is not available yet.
  • SUCCESSFUL: The payment was completed successfully.
  • PAID_OUT: The payment was completed successfully and the funds have already been included in a payout to the merchant.
  • FAILED: The payment did not complete successfully.
  • CANCELLED: The payment was cancelled or reversed and is no longer payable or payable to the merchant.
  • CANCEL_FAILED: An attempt to cancel or reverse the payment was not completed successfully.
  • REFUNDED: The payment was refunded in full or in part.
  • REFUND_FAILED: An attempt to refund the payment was not completed successfully.
  • CHARGEBACK: The payment was subject to a chargeback.
  • NON_COLLECTION: The amount could not be collected from the merchant after a chargeback or related adjustment.
tax_enabledboolean

Indicates whether tax deduction is enabled for the transaction.

Example response

{
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": "SUCCESSFUL",
  "payment_type": "ECOM",
  "installments_count": 1,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": "CUSTOMER_ENTRY",
  "auth_code": "053201",
  "product_summary": "Purchase",
  "payouts_total": 1,
  "payouts_received": 1,
  "payout_plan": "SINGLE_PAYMENT",
  "foreign_transaction_id": "J13253253x1",
  "client_transaction_id": "urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2",
  "username": "merchant@example.com",
  "fee_amount": 8,
  "lat": 52.520008,
  "lon": 13.404954,
  "horizontal_accuracy": 5,
  "merchant_id": 136902,
  "device_info": {
    "name": "m0xx",
    "system_name": "Android",
    "model": "GT-I9300",
    "system_version": "4.3",
    "uuid": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2"
  },
  "simple_payment_type": "CARD",
  "verification_method": "none",
  "card": {
    "last_4_digits": "3456",
    "type": "VISA",
    "payment_account_reference": "5665ABCDEFGHIJKLMNOPQRSTUVWXY"
  },
  "elv_account": {
    "sort_code": "87096214",
    "last_4_digits": "5674",
    "sequence_no": 1,
    "iban": "DE60870962140012345674"
  },
  "local_time": "2020-02-29T11:56:56+01:00",
  "payout_date": "2019-08-28",
  "payout_type": "BANK_ACCOUNT",
  "process_as": "CREDIT",
  "products": [
    {
      "name": "Purchase reader for merchant with code ME3FCAVF",
      "price_label": "EUR 100.00",
      "price": 100,
      "vat_rate": 0.19,
      "single_vat_amount": 19,
      "price_with_vat": 119,
      "vat_amount": 19,
      "quantity": 1,
      "total_price": 100,
      "total_with_vat": 119
    }
  ],
  "vat_rates": [
    {
      "rate": 0.045,
      "net": 1.36,
      "vat": 0.06,
      "gross": 1.42
    }
  ],
  "transaction_events": [
    {
      "id": 9567461191,
      "event_type": "REFUND",
      "status": "SUCCESSFUL",
      "amount": 58.8,
      "due_date": "2020-05-25",
      "date": "2020-05-25",
      "installment_number": 1,
      "timestamp": "2020-05-25T10:49:42.784Z"
    }
  ],
  "simple_status": "SUCCESSFUL",
  "links": [
    {
      "rel": "refund",
      "href": "https://api.sumup.com/v1.0/merchants/MH4H92C7/payments/4ffb8dfc-7f2b-413d-a497-2ad00766585e/refunds",
      "type": "application/json",
      "min_amount": 0.01,
      "max_amount": 10.1
    }
  ],
  "events": [
    {
      "id": 9567461191,
      "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "type": "REFUND",
      "status": "SUCCESSFUL",
      "amount": 10.1,
      "timestamp": "2020-05-25T10:49:42.784Z",
      "fee_amount": 0.25,
      "installment_number": 1,
      "deducted_amount": 10.1,
      "deducted_fee_amount": 0.25
    }
  ],
  "location": {
    "lat": 52.520008,
    "lon": 13.404954,
    "horizontal_accuracy": 5
  },
  "tax_enabled": true
}

Changes

  • fddb4ef1245aRevision changes
    • warning

      added the new SUMUP enum value to the // response property for the response status

  • 0f66b0a52002Revision changes
    • breaking

      the / response property's min was decreased from 0.00 to -90.00 for the response status

    • breaking

      the // response property's min was decreased from 0.00 to -90.00 for the response status

    • breaking

      the // response property's min was decreased from 0.00 to -180.00 for the response status

    • breaking

      the / response property's min was decreased from 0.00 to -180.00 for the response status

    • warning

      added the new BANCOMAT enum value to the // response property for the response status

    • info

      added the optional property // to the response with the status

    • info

      removed the BGN enum value from the / response property for the response status