SumUp REST API

SumUp’s REST API operates with application/json HTTP requests and response. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes. For testing our APIs make sure you have a SumUp Profile (you can create one here). To activate your SumUp Profile follow these steps.

Once you have an active SumUp Profile, go to developer.sumup.com and click on “Create” On the top right side, click on “Profile” followed by “Test profiles” Select your business country Click “Create” Copy and store safely the user name (format: 32 [email protected]) and randomly generated unique password.

Note: You will not be able to access your password afterwards make sure to store it safely before dismissing the message

Note: SumUp merchants are able to create up to 20 test profiles

When you receive your test profile you can create your client credentials and process different requests with real payment instruments, without charging them. Legal note: We reserve the right to change, modify, or remove the contents of this Website and SumUp APIs at any time without notice.

Server URL
 https://api.sumup.com  

Authorization

SumUp API uses API keys for authentication. You can view and manage your API keys in the API Keys section of the Developer Portal.

API keys are short static tokens that are passed in the Authorization header to authenticate the requests.

The tokens have a sup_sk_ prefix. Your API keys have access to the whole SumUp API, so make sure to keep them secure.

All requests must be made over HTTPS and must be authenticated.

Alternatively, SumUp APIs support OAuth2 authentication for applications that want to use SumUp as a platform for other users.

Read more about authorization in our Authorization guide.

Authorization

Request authorization from users

Request authorization from users and grant your application access to resources associated with the user's profile.

Query Parameters

response_type string

Example: "code"
client_id string

Example: "fOcmczrYtYMJ7Li5GjMLLcUeC9dN"
redirect_uri string

Example: "https://sample-app.example.com/callback"
scope string

Example: "payments"
state string

Example: "2cFCsY36y95lFHk4"

Response 200

 get 
 /authorize  
 curl https://api.sumup.com/authorize  

NoBody
 {}  

Authorization

Generate a token

Generate a token or a refresh token

Body Parameters

client_id string required

The client ID of your application that was generated when you registered it.

Example: "fOcmczrYtYMJ7Li5GjMLLcUeC9dN"
client_secret string required

The client secret of your application that was generated when you registered it.

Example: "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c"
code string required

The authorization code that you received from requesting an authorization code.

Example: "be366ce9fccd0c337d1da29b31d06dd1135ab95401562883"
grant_type string required

Options: authorization_code refresh_token

The grant type used for obtaining an access token.

Example: "refresh_token"
refresh_token string

A required parameter when generating a refresh token.

Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"

Response 200

access_token string

The access token that you need to use in your requests to the SumUp API.

Example: "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073"
expires_in integer

The validity of the access token in seconds.

Example: 3600
refresh_token string

The refresh token provided in the request call

Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"
scope string

List of authorization scopes granted to your access token.

Example: "payments user.app-settings transactions.history user.profile_readonly"
token_type string

The type of the token. The value is always Bearer.

Example: "Bearer"

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /token  
 curl https://api.sumup.com/token  

access_token
 {
  "access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "token_type": "Bearer"
}  

refresh_token
 {
  "access_token": "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "scope": "payments user.app-settings transactions.history user.profile_readonly",
  "token_type": "Bearer"
}  

Checkouts

Accept payments from your end users by adding the Checkouts model to your platform. SumUp supports standard and single payment 3DS checkout flows.

The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a checkout and then processing the checkout.

The Checkout object

Details of the payment checkout.

Attributes

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
currency string
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
id string

Unique ID of the checkout resource.
mandate object
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

The Checkout object
 {
  "amount": 10.1,
  "checkout_reference": null,
  "currency": "EUR",
  "customer_id": null,
  "date": "2020-02-29T10:56:56+00:00",
  "description": null,
  "id": null,
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": null,
  "pay_to_email": null,
  "return_url": null,
  "status": null,
  "transactions": [
    {
      "amount": 10.1,
      "currency": "EUR",
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "installments_count": null,
      "payment_type": null,
      "status": null,
      "timestamp": "2020-02-29T10:56:56.876Z",
      "transaction_code": "TEENSK4W2K",
      "auth_code": "053201",
      "entry_mode": null,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "tip_amount": 3,
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}  

Checkouts

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Scopes: payments

Query Parameters

checkout_reference string

Response 200

[]object

Show attributes

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

Example: "Purchase"
id string

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string

Unique identifying code of the merchant profile.

Example: "MH4H92C7"
pay_to_email string

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

Example: "[email protected]"
return_url string

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

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

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/checkouts  
 curl https://api.sumup.com/v0.1/checkouts  

[
  {
    "amount": 10.1,
    "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
    "currency": "EUR",
    "customer_id": "831ff8d4cd5958ab5670",
    "date": "2020-02-29T10:56:56+00:00",
    "description": "Purchase",
    "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
    "mandate": {
      "merchant_code": "MDASYTPD",
      "status": "active",
      "type": "recurrent"
    },
    "merchant_code": "MH4H92C7",
    "pay_to_email": "[email protected]",
    "return_url": null,
    "status": null,
    "transactions": [
      {
        "amount": 10.1,
        "currency": "EUR",
        "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
        "installments_count": null,
        "payment_type": null,
        "status": null,
        "timestamp": "2020-02-29T10:56:56.876Z",
        "transaction_code": "TEENSK4W2K",
        "auth_code": "053201",
        "entry_mode": null,
        "internal_id": 1763892018,
        "merchant_code": "MH4H92C7",
        "tip_amount": 3,
        "vat_amount": 6
      }
    ],
    "valid_until": "2020-02-29T10:56:56+00:00",
    "merchant_name": "Sample Merchant",
    "payment_instrument": {
      "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
    },
    "redirect_url": "https://mysite.com/completed_purchase",
    "transaction_code": "TEENSK4W2K",
    "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
  }
]

Checkouts

Create a checkout

Creates a new payment checkout resource. The unique checkout_reference created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the redirect_url parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

Scopes: payments

Body Parameters

amount number required

Amount of the payment.
checkout_reference string required

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
currency string required
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
id string

Unique ID of the checkout resource.
merchant_code string required

Unique identifying code of the merchant profile.
pay_to_email string

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.
payment_type string

Alternative payment method name

Example: "boleto"
personal_details object

Object containing personal details about the payer, typical for Boleto checkouts
Show attributes
Close

Attributes
- address object
  
  Payer's address information
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  Payer's city
  
  Example: "Rio de Janeiro"
  
  country string
  
  Payer's country
  
  Example: "BR"
  
  line_1 string
  
  Field for address details
  
  postal_code string
  
  Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit (more information about the format available here). Both options are accepted as correct.
  
  Example: "20000-000"
  
  state string
  
  Options: AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO
  
  Payer's state code
  
  Example: "RJ"
- email string
  
  Payer's email address
  
  Example: "[email protected]"
- first_name string
  
  Payer's first name
  
  Example: "John"
- last_name string
  
  Payer's last name
  
  Example: "Doe"
- tax_id string
  
  Payer's tax identification number (CPF)
  
  Example: "423.378.593-47"
purpose string

Options: CHECKOUT SETUP_RECURRING_PAYMENT

Purpose of the checkout.
redirect_url string

Required for 3DS checkouts. Refers to a URL where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
return_url string

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

Response 201

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
currency string
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
id string

Unique ID of the checkout resource.
mandate object
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

error_code string

Platform code for the error.
message string

Short description of the error.
param string

Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /v0.1/checkouts  
 curl https://api.sumup.com/v0.1/checkouts  

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "pay_to_email": "[email protected]",
  "redirect_url": "https://mysite.com/completed_purchase",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "date": "2021-06-29T11:08:36.000+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "merchant_name": "My company",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://sumup.com",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}

Checkouts

Retrieve a checkout

Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.

Scopes: payments

Path Parameters

id string required

Response 200

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

Example: "Purchase"
id string

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string

Unique identifying code of the merchant profile.

Example: "MH4H92C7"
pay_to_email string

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

Example: "[email protected]"
return_url string

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

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

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/checkouts/{id}  
 curl https://api.sumup.com/v0.1/checkouts/{id}  

{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MH4H92C7",
  "pay_to_email": "[email protected]",
  "return_url": null,
  "status": null,
  "transactions": [
    {
      "amount": 10.1,
      "currency": "EUR",
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "installments_count": null,
      "payment_type": null,
      "status": null,
      "timestamp": "2020-02-29T10:56:56.876Z",
      "transaction_code": "TEENSK4W2K",
      "auth_code": "053201",
      "entry_mode": null,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "tip_amount": 3,
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00",
  "merchant_name": "Sample Merchant",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "redirect_url": "https://mysite.com/completed_purchase",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
}

Checkouts

Process a checkout

Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the Create a checkout endpoint.

Follow this request with Retrieve a checkout to confirm its status.

Path Parameters

id string required

Body Parameters

card object
customer_id string

Required when token is provided. Unique ID of the customer.
installments integer

Number of installments for deferred payments. Available only to merchant users in Brazil.
mandate object
payment_type string required

Options: card boleto ideal blik bancontact
token string

Required when using a tokenized card to process a checkout. Unique token identifying the saved payment card for a customer.

Response 200

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

Example: "Purchase"
id string

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string

Unique identifying code of the merchant profile.

Example: "MH4H92C7"
pay_to_email string

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

Example: "[email protected]"
return_url string

URL to which the SumUp platform sends the processing status of the payment checkout.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

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

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 put 
 /v0.1/checkouts/{id}  
 curl https://api.sumup.com/v0.1/checkouts/{id}  

CheckoutSuccessBancontact
 {
  "next_step": {
    "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
      "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
      "tx": "624788471"
    },
    "url": "https://r3.girogate.de/ti/simbcmc"
  }
}  

{
  "amount": 10.1,
  "boleto": {
    "barcode": "34191090081790614310603072340007886840000000200",
    "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
  },
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "BRL",
  "date": "2021-07-06T12:34:02.000+00:00",
  "description": "Boleto checkout",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample shop",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://website.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "currency": "BRL",
      "entry_mode": "BOLETO",
      "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C9",
      "payment_type": "BOLETO",
      "status": "PENDING",
      "timestamp": "2021-07-06T12:34:16.460+00:00",
      "tip_amount": 3,
      "transaction_code": "TEN3E696NP",
      "vat_amount": 6
    }
  ]
}

{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MH4H92C7",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase with token",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "redirect_url": "https://mysite.com/completed_purchase",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}

CheckoutSuccessiDeal
 {
  "next_step": {
    "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
      "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
      "tx": "961473700"
    },
    "url": "https://r3.girogate.de/ti/simideal"
  }
}  

Checkouts

Deactivate a checkout

Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.

Scopes: payments

Path Parameters

id string required

Response 200

amount number

Amount of the payment.
checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
currency string
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
id string

Unique ID of the checkout resource.
merchant_code string

Unique identifying code of the merchant profile.
merchant_country string

The merchant's country
merchant_name string

Merchant name
pay_to_email string

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.
purpose string

Options: SETUP_RECURRING_PAYMENT CHECKOUT

Purpose of the checkout creation initially
status string

Options: EXPIRED

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 delete 
 /v0.1/checkouts/{id}  
 curl https://api.sumup.com/v0.1/checkouts/{id}  

{
  "amount": 2,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Deletion example",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "transactions": [],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

Checkouts

Get available payment methods

Get payment methods available for the given merchant to use with a checkout.

Scopes: payments

Path Parameters

merchant_code string required

Query Parameters

amount number
currency string

Response 200

available_payment_methods []object
Show attributes
Close

Attributes
- id string required
  
  The ID of the payment method.
  
  Example: "qr_code_pix"

details string

Details of the error.
failed_constraints []object
Show attributes
Close

Attributes
- message string
- reference string
status number

The status code.
title string

Short title of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/merchants/{merchant_code}/payment-methods  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods  

success
 {
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "blik"
    }
  ]
}  

Customers

Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform.

Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.

The Customer object

Attributes

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Create a customer

Creates a new saved customer resource which you can later manipulate and save payment instruments to.

Scopes: payment_instruments

Body Parameters

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Response 201

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /v0.1/customers  
 curl https://api.sumup.com/v0.1/customers  

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Retrieve a customer

Retrieves an identified saved customer resource through the unique customer_id parameter, generated upon customer creation.

Scopes: payment_instruments

Path Parameters

customer_id string required

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/customers/{customer_id}  
 curl https://api.sumup.com/v0.1/customers/{customer_id}  

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Update a customer

Updates an identified saved customer resource's personal details.

The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.

Scopes: payment_instruments

Path Parameters

customer_id string required

Body Parameters

personal_details object

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 put 
 /v0.1/customers/{customer_id}  
 curl https://api.sumup.com/v0.1/customers/{customer_id}  

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

List payment instruments

Lists all payment instrument resources that are saved for an identified customer.

Scopes: payment_instruments

Path Parameters

customer_id string required

Response 200

[]object

Show attributes

active boolean

Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a DELETE request to the resource endpoint.
card object

Details of the payment card.
Show attributes
Close

Attributes
- last_4_digits string
  
  Last 4 digits of the payment card number.
  
  Example: "3456"
- type string
  
  Options: AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card.
created_at string

Creation date of payment instrument. Response format expressed according to ISO8601 code.
mandate object
token string

Unique token identifying the saved payment card for a customer.
type string

Options: card

Type of the payment instrument.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/customers/{customer_id}/payment-instruments  
 curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments  

List payment instruments response
 [
  {
    "active": true,
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00",
    "mandate": {
      "merchant_code": "MDASYTPD",
      "status": "active",
      "type": "recurrent"
    },
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "type": "card"
  }
]  

Customers

Create a payment instrument

Creates and activates a new payment instrument resource by saving a payment card for an identified customer. Implement to improve customer experience by skipping the step of entering payment instrument details.

The token created via this endpoint can not be used for recurring payments by merchants operating within the EU. For more information visit our recurring payments guide.

Scopes: payment_instruments

Path Parameters

customer_id string required

Body Parameters

active boolean required

Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a DELETE request to the resource endpoint.
card object required
token string required

Unique token identifying the saved payment card for a customer.
type string required

Options: card

Type of the payment instrument.

Response 201

active boolean

Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a DELETE request to the resource endpoint.
card object

Details of the payment card.
Show attributes
Close

Attributes
- last_4_digits string
  
  Last 4 digits of the payment card number.
  
  Example: "3456"
- type string
  
  Options: AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card.
created_at string

Creation date of payment instrument. Response format expressed according to ISO8601 code.
mandate object
token string

Unique token identifying the saved payment card for a customer.
type string

Options: card

Type of the payment instrument.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /v0.1/customers/{customer_id}/payment-instruments  
 curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments  

Create a payment instrument response
 {
  "active": true,
  "card": {
    "last_4_digits": "0001",
    "type": "VISA"
  },
  "created_at": "2021-03-30T10:06:07.000+00:00",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
  "type": "card"
}  

Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Scopes: payment_instruments

Path Parameters

customer_id string required
token string required

Response 204

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 delete 
 /v0.1/customers/{customer_id}/payment-instruments/{token}  
 curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token}  

NoBody
 {}  

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Attributes

account object
app_settings object
is_migrated_payleven_br boolean

Merchant comes from payleven BR migration
merchant_profile object
operators []object
permissions object
personal_profile object

The Merchant Account object
 {
  "account": {
    "type": null,
    "username": null
  },
  "app_settings": {
    "advanced_mode": null,
    "barcode_scanner": null,
    "cash_payment": null,
    "checkout_preference": null,
    "expected_max_transaction_amount": null,
    "include_vat": null,
    "manual_entry": null,
    "manual_entry_tutorial": null,
    "mobile_payment": null,
    "mobile_payment_tutorial": null,
    "reader_payment": null,
    "referral": null,
    "tax_enabled": null,
    "terminal_mode_tutorial": null,
    "tip_rates": [
      null
    ],
    "tipping": null
  },
  "is_migrated_payleven_br": null,
  "merchant_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "bank_accounts": [
      {
        "account_category": null,
        "account_holder_name": null,
        "account_number": null,
        "account_type": null,
        "bank_code": null,
        "bank_name": null,
        "branch_code": null,
        "created_at": null,
        "iban": null,
        "primary": null,
        "status": null,
        "swift": null
      }
    ],
    "business_owners": [
      {
        "date_of_birth": null,
        "first_name": null,
        "landline": null,
        "last_name": null,
        "mobile_phone": null,
        "ownership": null
      }
    ],
    "company_name": null,
    "company_registration_number": null,
    "country": null,
    "doing_business_as": {
      "address": {
        "address_line1": null,
        "address_line2": null,
        "city": null,
        "country": null,
        "post_code": null,
        "region_id": null,
        "region_name": null
      },
      "business_name": null,
      "company_registration_number": null,
      "email": null,
      "vat_id": null,
      "website": null
    },
    "extdev": null,
    "legal_type": {
      "description": null,
      "full_description": null,
      "id": null,
      "sole_trader": null
    },
    "locale": null,
    "merchant_category_code": null,
    "merchant_code": null,
    "mobile_phone": null,
    "nature_and_purpose": null,
    "payout_zone_migrated": null,
    "permanent_certificate_access_code": null,
    "settings": {
      "adyen_company": null,
      "adyen_merchant_code": null,
      "adyen_password": null,
      "adyen_user": null,
      "daily_payout_email": null,
      "gross_settlement": null,
      "monthly_payout_email": null,
      "moto_payment": null,
      "payout_instrument": null,
      "payout_on_demand": null,
      "payout_on_demand_available": null,
      "payout_period": null,
      "payout_type": null,
      "printers_enabled": null,
      "stone_merchant_code": null,
      "tax_enabled": null
    },
    "vat_id": null,
    "vat_rates": {
      "country": null,
      "description": null,
      "id": null,
      "ordering": null,
      "rate": null
    },
    "website": null
  },
  "operators": [
    {
      "username": null
    }
  ],
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "personal_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "complete": null,
    "date_of_birth": null,
    "first_name": null,
    "last_name": null,
    "mobile_phone": null
  }
}  

Merchant

Retrieve a profile

Returns user profile information.

Scopes: user.profile user.profile_readonly

Query Parameters

include[] []string

Response 200

account object
app_settings object
is_migrated_payleven_br boolean

Merchant comes from payleven BR migration
merchant_profile object
operators []object
permissions object
personal_profile object

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me  
 curl https://api.sumup.com/v0.1/me  

Retrieve a profile response
 {
  "account": {
    "type": null,
    "username": null
  },
  "app_settings": {
    "advanced_mode": null,
    "barcode_scanner": null,
    "cash_payment": null,
    "checkout_preference": null,
    "expected_max_transaction_amount": null,
    "include_vat": null,
    "manual_entry": null,
    "manual_entry_tutorial": null,
    "mobile_payment": null,
    "mobile_payment_tutorial": null,
    "reader_payment": null,
    "referral": null,
    "tax_enabled": null,
    "terminal_mode_tutorial": null,
    "tip_rates": [
      null
    ],
    "tipping": null
  },
  "is_migrated_payleven_br": null,
  "merchant_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "bank_accounts": [
      {
        "account_category": null,
        "account_holder_name": null,
        "account_number": null,
        "account_type": null,
        "bank_code": null,
        "bank_name": null,
        "branch_code": null,
        "created_at": null,
        "iban": null,
        "primary": null,
        "status": null,
        "swift": null
      }
    ],
    "business_owners": [
      {
        "date_of_birth": null,
        "first_name": null,
        "landline": null,
        "last_name": null,
        "mobile_phone": null,
        "ownership": null
      }
    ],
    "company_name": null,
    "company_registration_number": null,
    "country": null,
    "doing_business_as": {
      "address": {
        "address_line1": null,
        "address_line2": null,
        "city": null,
        "country": null,
        "post_code": null,
        "region_id": null,
        "region_name": null
      },
      "business_name": null,
      "company_registration_number": null,
      "email": null,
      "vat_id": null,
      "website": null
    },
    "extdev": null,
    "legal_type": {
      "description": null,
      "full_description": null,
      "id": null,
      "sole_trader": null
    },
    "locale": null,
    "merchant_category_code": null,
    "merchant_code": null,
    "mobile_phone": null,
    "nature_and_purpose": null,
    "payout_zone_migrated": null,
    "permanent_certificate_access_code": null,
    "settings": {
      "adyen_company": null,
      "adyen_merchant_code": null,
      "adyen_password": null,
      "adyen_user": null,
      "daily_payout_email": null,
      "gross_settlement": null,
      "monthly_payout_email": null,
      "moto_payment": null,
      "payout_instrument": null,
      "payout_on_demand": null,
      "payout_on_demand_available": null,
      "payout_period": null,
      "payout_type": null,
      "printers_enabled": null,
      "stone_merchant_code": null,
      "tax_enabled": null
    },
    "vat_id": null,
    "vat_rates": {
      "country": null,
      "description": null,
      "id": null,
      "ordering": null,
      "rate": null
    },
    "website": null
  },
  "operators": [
    {
      "username": null
    }
  ],
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "personal_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "complete": null,
    "date_of_birth": null,
    "first_name": null,
    "last_name": null,
    "mobile_phone": null
  }
}  

Merchant

Retrieve a merchant profile

Retrieves merchant profile data.

Scopes: user.profile user.profile_readonly

Response 200

address object
bank_accounts []object
Show attributes
Close

Attributes
- account_category string
  
  Account category - business or personal
- account_holder_name string
- account_number string
  
  Account number
- account_type string
  
  Type of the account
- bank_code string
  
  Bank code
- bank_name string
  
  Bank name
- branch_code string
  
  Branch code
- created_at string
  
  Creation date of the bank account
- iban string
  
  IBAN
- primary boolean
  
  The primary bank account is the one used for settlements
- status string
  
  Status in the verification process
- swift string
  
  SWIFT code
business_owners []object
company_name string

Company name
company_registration_number string

Company registration number
country string

Merchant country isocode (for internal usage only)
doing_business_as object
extdev boolean

True if the merchant is extdev
legal_type object
locale string

Merchant locale (for internal usage only)
merchant_category_code string

Merchant category code
merchant_code string

Unique identifying code of the merchant profile
mobile_phone string

Mobile phone number
nature_and_purpose string

Nature and purpose of the business
payout_zone_migrated boolean

True if the payout zone of this merchant is migrated
permanent_certificate_access_code string

Permanent certificate access code (Portugal)
settings object
vat_id string

Vat ID
vat_rates object
website string

Website

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile  
 curl https://api.sumup.com/v0.1/me/merchant-profile  

Retrieve a merchant profile response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "company": null,
    "country": null,
    "country_details": {
      "currency": null,
      "en_name": null,
      "iso_code": null,
      "native_name": null
    },
    "first_name": null,
    "landline": null,
    "last_name": null,
    "post_code": null,
    "region_code": null,
    "region_id": null,
    "region_name": null,
    "state_id": null,
    "timeoffset_details": {
      "dst": null,
      "offset": null,
      "post_code": null
    }
  },
  "bank_accounts": [
    {
      "account_category": null,
      "account_holder_name": null,
      "account_number": null,
      "account_type": null,
      "bank_code": null,
      "bank_name": null,
      "branch_code": null,
      "created_at": null,
      "iban": null,
      "primary": null,
      "status": null,
      "swift": null
    }
  ],
  "business_owners": [
    {
      "date_of_birth": null,
      "first_name": null,
      "landline": null,
      "last_name": null,
      "mobile_phone": null,
      "ownership": null
    }
  ],
  "company_name": null,
  "company_registration_number": null,
  "country": null,
  "doing_business_as": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "country": null,
      "post_code": null,
      "region_id": null,
      "region_name": null
    },
    "business_name": null,
    "company_registration_number": null,
    "email": null,
    "vat_id": null,
    "website": null
  },
  "extdev": null,
  "legal_type": {
    "description": null,
    "full_description": null,
    "id": null,
    "sole_trader": null
  },
  "locale": null,
  "merchant_category_code": null,
  "merchant_code": null,
  "mobile_phone": null,
  "nature_and_purpose": null,
  "payout_zone_migrated": null,
  "permanent_certificate_access_code": null,
  "settings": {
    "adyen_company": null,
    "adyen_merchant_code": null,
    "adyen_password": null,
    "adyen_user": null,
    "daily_payout_email": null,
    "gross_settlement": null,
    "monthly_payout_email": null,
    "moto_payment": null,
    "payout_instrument": null,
    "payout_on_demand": null,
    "payout_on_demand_available": null,
    "payout_period": null,
    "payout_type": null,
    "printers_enabled": null,
    "stone_merchant_code": null,
    "tax_enabled": null
  },
  "vat_id": null,
  "vat_rates": {
    "country": null,
    "description": null,
    "id": null,
    "ordering": null,
    "rate": null
  },
  "website": null
}  

Merchant

List bank accounts

Retrives bank accounts of the merchant.

Scopes: user.payout-settings user.profile user.profile_readonly

Query Parameters

primary boolean

Response 200

[]object

Show attributes

account_category string

Account category - business or personal
account_holder_name string
account_number string

Account number
account_type string

Type of the account
bank_code string

Bank code
bank_name string

Bank name
branch_code string

Branch code
created_at string

Creation date of the bank account
iban string

IBAN
primary boolean

The primary bank account is the one used for settlements
status string

Status in the verification process
swift string

SWIFT code

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile/bank-accounts  
 curl https://api.sumup.com/v0.1/me/merchant-profile/bank-accounts  

List bank accounts response
 [
  {
    "account_category": null,
    "account_holder_name": null,
    "account_number": null,
    "account_type": null,
    "bank_code": null,
    "bank_name": null,
    "branch_code": null,
    "created_at": null,
    "iban": null,
    "primary": null,
    "status": null,
    "swift": null
  }
]  

Merchant

Retrieve DBA

Retrieves Doing Business As profile.

Scopes: user.profile user.profile_readonly

Response 200

address object
Show attributes
Close

Attributes
- address_line1 string
  
  Address line 1
- address_line2 string
  
  Address line 2
- city string
  
  City
- country string
  
  Country ISO 3166-1 code
- post_code string
  
  Postal code
- region_id number
  
  Country region ID
- region_name string
  
  Country region name
business_name string

Doing business as name
company_registration_number string

Doing business as company registration number
email string

Doing business as email
vat_id string

Doing business as VAT ID
website string

Doing business as website

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/merchant-profile/doing-business-as  
 curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as  

Retrieve DBA response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "post_code": null,
    "region_id": null,
    "region_name": null
  },
  "business_name": null,
  "company_registration_number": null,
  "email": null,
  "vat_id": null,
  "website": null
}  

Merchant

Get settings

Retrieves merchant settings.

Scopes: user.payout-settings

Response 200

adyen_company string

Adyen company
adyen_merchant_code string

Adyen merchant code
adyen_password string

Adyen password
adyen_user string

Adyen username
daily_payout_email boolean

Whether merchant will receive daily payout emails
gross_settlement boolean

Whether merchant has gross settlement enabled
monthly_payout_email boolean

Whether merchant will receive monthly payout emails
moto_payment string

Options: UNAVAILABLE ENFORCED ON OFF

Whether merchant can make MOTO payments
payout_instrument string

Payout Instrument
payout_on_demand boolean

Whether merchant will receive payouts on demand
payout_on_demand_available boolean

Whether merchant can edit payouts on demand
payout_period string

Payout frequency
payout_type string

Payout type
printers_enabled boolean

Whether to show printers in mobile app
stone_merchant_code string

Stone merchant code
tax_enabled boolean

Whether to show tax in receipts (saved per transaction)

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile/settings  
 curl https://api.sumup.com/v0.1/me/merchant-profile/settings  

Get settings response
 {
  "adyen_company": null,
  "adyen_merchant_code": null,
  "adyen_password": null,
  "adyen_user": null,
  "daily_payout_email": null,
  "gross_settlement": null,
  "monthly_payout_email": null,
  "moto_payment": null,
  "payout_instrument": null,
  "payout_on_demand": null,
  "payout_on_demand_available": null,
  "payout_period": null,
  "payout_type": null,
  "printers_enabled": null,
  "stone_merchant_code": null,
  "tax_enabled": null
}  

Merchant

Retrieve a personal profile

Retrieves personal profile data.

Scopes: user.profile user.profile_readonly

Response 200

address object
complete boolean
date_of_birth string

Date of birth
first_name string

First name of the user
last_name string

Last name of the user
mobile_phone string

Mobile phone number

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/personal-profile  
 curl https://api.sumup.com/v0.1/me/personal-profile  

Retrieve a personal profile response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "company": null,
    "country": null,
    "country_details": {
      "currency": null,
      "en_name": null,
      "iso_code": null,
      "native_name": null
    },
    "first_name": null,
    "landline": null,
    "last_name": null,
    "post_code": null,
    "region_code": null,
    "region_id": null,
    "region_name": null,
    "state_id": null,
    "timeoffset_details": {
      "dst": null,
      "offset": null,
      "post_code": null
    }
  },
  "complete": null,
  "date_of_birth": null,
  "first_name": null,
  "last_name": null,
  "mobile_phone": null
}  

Subaccounts

Manage subaccounts.

The Sub-Account object

Attributes

created_at string required

Creation date of the operator

Example: "2022-12-11T13:46:00Z"
disabled boolean required

True if the subaccount is disabled.
id number required

ID of the sub-account

Example: 123
permissions object required
updated_at string required

Example: "2022-12-12T14:46:00Z"
username string required

Username of the operator

Example: "[email protected]"

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

List subaccounts

Scopes: user.subaccounts

Response 200

[]object

Show attributes

created_at string required

Creation date of the operator

Example: "2022-12-11T13:46:00Z"
disabled boolean required

True if the subaccount is disabled.
id number required

ID of the sub-account

Example: 123
permissions object required
updated_at string required

Example: "2022-12-12T14:46:00Z"
username string required

Username of the operator

Example: "[email protected]"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/accounts  
 curl https://api.sumup.com/v0.1/me/accounts  

[
  {
    "created_at": "2022-12-11T13:46:00Z",
    "disabled": false,
    "id": 123,
    "permissions": {
      "create_moto_payments": null,
      "create_referral": null,
      "full_transaction_history_view": null,
      "refund_transactions": null
    },
    "updated_at": "2022-12-12T14:46:00Z",
    "username": "[email protected]"
  }
]

Subaccounts

Create a subaccount

Scopes: user.subaccounts

Body Parameters

password string

Password
username string

Username of the new sub-account. Must be a valid email address.

Response 200

created_at string required

Creation date of the operator

Example: "2022-12-11T13:46:00Z"
disabled boolean required

True if the subaccount is disabled.
id number required

ID of the sub-account

Example: 123
permissions object required
updated_at string required

Example: "2022-12-12T14:46:00Z"
username string required

Username of the operator

Example: "[email protected]"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 post 
 /v0.1/me/accounts  
 curl https://api.sumup.com/v0.1/me/accounts  

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

Update a subaccount

Scopes: user.subaccounts

Path Parameters

operator_code string required

Body Parameters

password string

Password
username string

Username of the new sub-account. Must be a valid email address.

Response 200

created_at string required

Creation date of the operator

Example: "2022-12-11T13:46:00Z"
disabled boolean required

True if the subaccount is disabled.
id number required

ID of the sub-account

Example: 123
permissions object required
updated_at string required

Example: "2022-12-12T14:46:00Z"
username string required

Username of the operator

Example: "[email protected]"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 put 
 /v0.1/me/accounts/{operator_code}  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_code}  

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

Deactivate a subaccount

Scopes: user.subaccounts

Path Parameters

operator_code string required

Response 200

created_at string required

Creation date of the operator

Example: "2022-12-11T13:46:00Z"
disabled boolean required

True if the subaccount is disabled.
id number required

ID of the sub-account

Example: 123
permissions object required
updated_at string required

Example: "2022-12-12T14:46:00Z"
username string required

Username of the operator

Example: "[email protected]"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 delete 
 /v0.1/me/accounts/{operator_code}  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_code}  

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Payouts

The Payouts model will allow you to track funds you’ve received from SumUp. You can receive a detailed payouts list with information like dates, fees, references and statuses, using the List payouts endpoint.

For a less detailed payouts list use List transactions.'

The Financial Payouts object

Attributes

[]object

Show attributes

amount number
currency string
date string
fee number
id integer
reference string
status string

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

The Financial Payouts object
 [
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]  

Payouts

List payouts

Lists ordered payouts for the merchant profile.

Scopes: user.profile user.profile_readonly

Query Parameters

start_date string required
end_date string required
format string
limit integer
order string

Response 200

[]object

Show attributes

amount number
currency string
date string
fee number
id integer
reference string
status string

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/financials/payouts  
 curl https://api.sumup.com/v0.1/me/financials/payouts  

List payouts response
 [
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]  

Transactions

Retrieve details for a specific transaction by it’s id or any other required query parameter, or list all transactions related to the merchant account.

Transactions

List financial transactions

Lists a less detailed history of all transactions associated with the merchant profile.

Scopes: user.profile user.profile_readonly

Query Parameters

start_date string required
end_date string required
format string
limit integer
order string

Response 200

[]object

Show attributes

amount number
currency string
external_reference string
id string
timestamp string
transaction_code string
type string

Options: SALE REFUND CHARGE_BACK DD_RETURN DD_RETURN_REVERSAL

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/financials/transactions  
 curl https://api.sumup.com/v0.1/me/financials/transactions  

List financial transactions response
 [
  {
    "amount": null,
    "currency": null,
    "external_reference": null,
    "id": null,
    "timestamp": null,
    "transaction_code": null,
    "type": null
  }
]  

Transactions

Refund a transaction

Refunds an identified transaction either in full or partially.

Scopes: payments

Path Parameters

txn_id string required

Body Parameters

amount number

Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.

Response 204

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /v0.1/me/refund/{txn_id}  
 curl https://api.sumup.com/v0.1/me/refund/{txn_id}  

NoBody
 {}  

Transactions

Retrieve a transaction

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
internal_id
transaction_code
foreign_transaction_id
client_transaction_id

Scopes: transactions.history

Query Parameters

id string
internal_id string
transaction_code string

Response 200

amount number

Total amount of the transaction.

Example: 10.1
currency string
id string

Unique ID of the transaction.

Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
installments_count integer

Current number of the installment for deferred payments.
payment_type string

Options: ECOM RECURRING BOLETO

Payment type used for the transaction.
status string

Options: SUCCESSFUL CANCELLED FAILED PENDING

Current status of the transaction.
timestamp string

Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56.876Z"
transaction_code string

Transaction code returned by the acquirer/processing entity after processing the transaction.

Example: "TEENSK4W2K"
auth_code string

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

Example: "053201"
entry_mode string

Options: CUSTOMER_ENTRY BOLETO

Entry mode of the payment details.
internal_id integer

Internal unique ID of the transaction on the SumUp platform.

Example: 1763892018
merchant_code string

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

Example: "MH4H92C7"
tip_amount number

Amount of the tip (out of the total transaction amount).

Example: 3
vat_amount number

Amount of the applicable VAT (out of the total transaction amount).

Example: 6
payout_plan string

Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

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

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

Short description of the payment. The value is taken from the description property of the related checkout resource.
card object
events []object

List of events related to the transaction.
Show attributes
Close

Attributes
- amount number
- deducted_amount number
  
  Amount deducted for the event.
- deducted_fee_amount number
  
  Amount of the fee deducted for the event.
- fee_amount number
  
  Amount of the fee related to the event.
- id integer
- installment_number integer
  
  Consecutive number of the installment.
- status string
- timestamp string
- transaction_id string
- type string
horizontal_accuracy number
lat number
links []object

List of hyperlinks for accessing related resources.
Show attributes
Close

Attributes
local_time string

Local date and time of the creation of the transaction.
location object

Details of the payment location as received from the payment terminal.
Show attributes
Close

Attributes
- horizontal_accuracy number
- lat number
- lon number
lon number
payout_type string

Options: BANK_ACCOUNT BALANCE PREPAID_CARD

Payout type for the transaction.
products []object

List of products from the merchant's catalogue for which the transaction serves as a payment.
Show attributes
Close

Attributes
- name string
  
  Name of the product from the merchant's catalog.
- price number
  
  Price of the product without VAT.
- price_with_vat number
  
  Price of a single product item with VAT.
- quantity number
  
  Number of product items for the purchase.
- single_vat_amount number
  
  Amount of the VAT for a single product item (calculated as the product of price and vat_rate, i.e. single_vat_amount = price * vat_rate).
- total_price number
  
  Total price of the product items without VAT (calculated as the product of price and quantity, i.e. total_price = price * quantity).
- total_with_vat number
  
  Total price of the product items including VAT (calculated as the product of price_with_vat and quantity, i.e. total_with_vat = price_with_vat * quantity).
- vat_amount number
  
  Total VAT amount for the purchase (calculated as the product of single_vat_amount and quantity, i.e. vat_amount = single_vat_amount * quantity).
- vat_rate number
  
  VAT rate applicable to the product.
simple_payment_type string

Options: MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

Simple name of the payment type.
simple_status string

Options: SUCCESSFUL PAID_OUT CANCEL_FAILED CANCELLED CHARGEBACK FAILED REFUND_FAILED REFUNDED NON_COLLECTION

Status generated from the processing status and the latest transaction state.
tax_enabled boolean

Indicates whether tax deduction is enabled for the transaction.
transaction_events []object

List of transaction events related to the transaction.
Show attributes
Close

Attributes
- amount number
- date string
  
  Date when the transaction event occurred.
- due_date string
  
  Date when the transaction event is due to occur.
- event_type string
- id integer
- installment_number integer
  
  Consequtive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.
- status string
- timestamp string
username string

Email address of the registered user (merchant) to whom the payment is made.
vat_rates []object

List of VAT rates applicable to the transaction.
Show attributes
Close

Attributes
verification_method string

Options: none signature offline pin online pin offline pin + signature confirmation code verified

Verification method used for the transaction.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/transactions  
 curl https://api.sumup.com/v0.1/me/transactions  

Retrieve a transaction response
 {
  "amount": 10.1,
  "currency": "EUR",
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "installments_count": null,
  "payment_type": null,
  "status": null,
  "timestamp": "2020-02-29T10:56:56.876Z",
  "transaction_code": "TEENSK4W2K",
  "auth_code": "053201",
  "entry_mode": null,
  "internal_id": 1763892018,
  "merchant_code": "MH4H92C7",
  "tip_amount": 3,
  "vat_amount": 6,
  "payout_plan": null,
  "payouts_received": null,
  "payouts_total": null,
  "product_summary": null,
  "card": {
    "cvv": "123",
    "expiry_month": null,
    "expiry_year": "2023",
    "last_4_digits": "3456",
    "name": "FIRSTNAME LASTNAME",
    "number": "1234567890123456",
    "type": null,
    "zip_code": "12345"
  },
  "events": [
    {
      "amount": null,
      "deducted_amount": null,
      "deducted_fee_amount": null,
      "fee_amount": null,
      "id": null,
      "installment_number": null,
      "status": null,
      "timestamp": null,
      "transaction_id": null,
      "type": null
    }
  ],
  "horizontal_accuracy": null,
  "lat": null,
  "links": [
    null
  ],
  "local_time": null,
  "location": {
    "horizontal_accuracy": null,
    "lat": null,
    "lon": null
  },
  "lon": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "price_with_vat": null,
      "quantity": null,
      "single_vat_amount": null,
      "total_price": null,
      "total_with_vat": null,
      "vat_amount": null,
      "vat_rate": null
    }
  ],
  "simple_payment_type": null,
  "simple_status": null,
  "tax_enabled": null,
  "transaction_events": [
    {
      "amount": null,
      "date": null,
      "due_date": null,
      "event_type": null,
      "id": null,
      "installment_number": null,
      "status": null,
      "timestamp": null
    }
  ],
  "username": null,
  "vat_rates": [
    null
  ],
  "verification_method": null
}  

Transactions

List transactions

Lists detailed history of all transactions associated with the merchant profile.

Scopes: transactions.history

Query Parameters

transaction_code string
order string
limit integer
users []string
statuses []string
payment_types []string
types []string
changes_since string
newest_time string
newest_ref string
oldest_time string
oldest_ref string

Response 200

items []object
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- payout_plan string
  
  Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT
  
  Payout plan of the registered user at the time when the transaction was made.
- payouts_received integer
  
  Number of payouts that are made to the registered user specified in the user property.
- payouts_total integer
  
  Total number of payouts to the registered user specified in the user property.
- product_summary string
  
  Short description of the payment. The value is taken from the description property of the related checkout resource.
- card_type string
  
  Options: VISA AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card used for the transaction.
- transaction_id string
- type string
  
  Options: PAYMENT REFUND CHARGE_BACK
  
  Type of the transaction for the registered user specified in the user property.
- user string
  
  Email address of the registered user (merchant) to whom the payment is made.
links []object
Show attributes
Close

Attributes
- href string
  
  URL for accessing the related resource.
- rel string
  
  Specifies the relation to the current resource.
- type string
  
  Specifies the media type of the related resource.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/transactions/history  
 curl https://api.sumup.com/v0.1/me/transactions/history  

List transactions response
 {
  "items": [
    {
      "amount": 10.1,
      "currency": "EUR",
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "installments_count": null,
      "payment_type": null,
      "status": null,
      "timestamp": "2020-02-29T10:56:56.876Z",
      "transaction_code": "TEENSK4W2K",
      "payout_plan": null,
      "payouts_received": null,
      "payouts_total": null,
      "product_summary": null,
      "card_type": null,
      "transaction_id": null,
      "type": null,
      "user": null
    }
  ],
  "links": [
    {
      "href": null,
      "rel": null,
      "type": null
    }
  ]
}  

API Keys

API Keys allow your application to gain programmatic access to SumUp. API Keys allow application to do authorized requests within the SumUp ecosystem. API Keys are scopes to single account and thus can't be used for endpoints where user presence is needed (for such endpoints it is necessary to use OAuth2).

The API Key object

Attributes

created_at string required

Example: "2023-01-20T15:16:17Z"
id string required

Unique identifier of the API Key.

Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required

User-assigned name of the API Key.

Example: "My API Key"
plaintext string

The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required

Last 8 characters of the API key.

Example: "p6cL1vyZ"
scopes []string required
type string required

Options: public secret

Example: "secret"
updated_at string required

Example: "2023-01-20T15:16:17Z"

The API Key object
 {
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}  

API Keys

List API keys

Returns paginated list of API keys.

Scopes: api_keys

Path Parameters

merchant_code string required

Query Parameters

offset integer
limit integer

Response 200

items []object required
Show attributes
Close

Attributes
- created_at string required
  
  Example: "2023-01-20T15:16:17Z"
- id string required
  
  Unique identifier of the API Key.
  
  Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
  
  User-assigned name of the API Key.
  
  Example: "My API Key"
- plaintext string
  
  The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
  
  Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
  
  Last 8 characters of the API key.
  
  Example: "p6cL1vyZ"
- scopes []string required
- type string required
  
  Options: public secret
  
  Example: "secret"
- updated_at string required
  
  Example: "2023-01-20T15:16:17Z"
total_count integer required

 get 
 /v0.1/merchants/{merchant_code}/api-keys  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys  

List API keys response
 {
  "items": [
    {
      "created_at": "2023-03-24T10:10:10Z",
      "id": "sup_pk_1tpmgizNLHMkx1DdKd2hdzorZAaf6AcZ9",
      "name": "",
      "preview": "Aaf6AcZ9",
      "scopes": [],
      "type": "public",
      "updated_at": "2023-03-24T10:10:10Z"
    },
    {
      "created_at": "2023-03-25T09:10:10Z",
      "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
      "name": "Test Key",
      "preview": "TGhqew1b",
      "scopes": [
        "transactions.history",
        "user.app-settings",
        "user.profile_readonly",
        "user.profile",
        "user.subaccounts",
        "user.payout-settings",
        "products",
        "payments",
        "payment_instruments",
        "terminals.read",
        "terminals.write"
      ],
      "type": "secret",
      "updated_at": "2023-03-25T09:10:10Z"
    }
  ],
  "total_count": 2
}  

API Keys

Create an API key

Creates a new API key for the user.

Scopes: api_keys:write

Path Parameters

merchant_code string required

Body Parameters

name string required

Example: "New Key Name"
scopes []string required

Response 201

created_at string required

Example: "2023-01-20T15:16:17Z"
id string required

Unique identifier of the API Key.

Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required

User-assigned name of the API Key.

Example: "My API Key"
plaintext string

The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required

Last 8 characters of the API key.

Example: "p6cL1vyZ"
scopes []string required
type string required

Options: public secret

Example: "secret"
updated_at string required

Example: "2023-01-20T15:16:17Z"

 post 
 /v0.1/merchants/{merchant_code}/api-keys  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys  

Create an API key response
 {
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}  

API Keys

Retrieve an API Key

Gets an API key.

Scopes: api_keys

Path Parameters

merchant_code string required
key_id string required

Response 200

created_at string required

Example: "2023-01-20T15:16:17Z"
id string required

Unique identifier of the API Key.

Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required

User-assigned name of the API Key.

Example: "My API Key"
plaintext string

The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required

Last 8 characters of the API key.

Example: "p6cL1vyZ"
scopes []string required
type string required

Options: public secret

Example: "secret"
updated_at string required

Example: "2023-01-20T15:16:17Z"

 get 
 /v0.1/merchants/{merchant_code}/api-keys/{key_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}  

Retrieve an API Key response
 {
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}  

API Keys

Update an API key

Updates an API key.

Scopes: api_keys:write

Path Parameters

merchant_code string required
key_id string required

Body Parameters

name string required

New name for the API key.

Example: "My API Key"
scopes []string required

 put 
 /v0.1/merchants/{merchant_code}/api-keys/{key_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}  

API Keys

Revoke an API key

Revokes an API key.

Scopes: api_keys:write

Path Parameters

merchant_code string required
key_id string required

 delete 
 /v0.1/merchants/{merchant_code}/api-keys/{key_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}  

Receipts

The Receipts model obtains receipt-like details for specific transactions.

The Receipt object

Attributes

acquirer_data object
Show attributes
Close

Attributes
- authorization_code string
- local_time string
- return_code string
- tid string
emv_data object
Show attributes
Close

Attributes
merchant_data object
transaction_data object

The Receipt object
 {
  "acquirer_data": {
    "authorization_code": null,
    "local_time": null,
    "return_code": null,
    "tid": null
  },
  "emv_data": {},
  "merchant_data": {
    "locale": null,
    "merchant_profile": {
      "address": {
        "address_line1": null,
        "city": null,
        "country": null,
        "country_en_name": null,
        "country_native_name": null,
        "landline": null,
        "post_code": null
      },
      "business_name": null,
      "email": null,
      "merchant_code": null
    }
  },
  "transaction_data": {
    "amount": null,
    "card": {
      "last_4_digits": null,
      "type": null
    },
    "currency": null,
    "entry_mode": null,
    "events": [
      {
        "amount": null,
        "id": null,
        "receipt_no": null,
        "status": null,
        "timestamp": null,
        "transaction_id": null,
        "type": null
      }
    ],
    "installments_count": null,
    "payment_type": null,
    "products": [
      {
        "description": null,
        "name": null,
        "price": null,
        "quantity": null,
        "total_price": null
      }
    ],
    "receipt_no": null,
    "status": null,
    "timestamp": null,
    "tip_amount": null,
    "transaction_code": null,
    "vat_amount": null,
    "vat_rates": [
      {
        "gross": null,
        "net": null,
        "rate": null,
        "vat": null
      }
    ],
    "verification_method": null
  }
}  

Receipts

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Scopes:

Path Parameters

id string required

Query Parameters

mid string required
tx_event_id integer

Response 200

acquirer_data object
Show attributes
Close

Attributes
- authorization_code string
- local_time string
- return_code string
- tid string
emv_data object
Show attributes
Close

Attributes
merchant_data object
transaction_data object

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v1.1/receipts/{id}  
 curl https://api.sumup.com/v1.1/receipts/{id}  

Retrieve receipt details response
 {
  "acquirer_data": {
    "authorization_code": null,
    "local_time": null,
    "return_code": null,
    "tid": null
  },
  "emv_data": {},
  "merchant_data": {
    "locale": null,
    "merchant_profile": {
      "address": {
        "address_line1": null,
        "city": null,
        "country": null,
        "country_en_name": null,
        "country_native_name": null,
        "landline": null,
        "post_code": null
      },
      "business_name": null,
      "email": null,
      "merchant_code": null
    }
  },
  "transaction_data": {
    "amount": null,
    "card": {
      "last_4_digits": null,
      "type": null
    },
    "currency": null,
    "entry_mode": null,
    "events": [
      {
        "amount": null,
        "id": null,
        "receipt_no": null,
        "status": null,
        "timestamp": null,
        "transaction_id": null,
        "type": null
      }
    ],
    "installments_count": null,
    "payment_type": null,
    "products": [
      {
        "description": null,
        "name": null,
        "price": null,
        "quantity": null,
        "total_price": null
      }
    ],
    "receipt_no": null,
    "status": null,
    "timestamp": null,
    "tip_amount": null,
    "transaction_code": null,
    "vat_amount": null,
    "vat_rates": [
      {
        "gross": null,
        "net": null,
        "rate": null,
        "vat": null
      }
    ],
    "verification_method": null
  }
}  

SumUp REST API

Authorization

Request authorization from users

Query Parameters

Response 200

Generate a token

Body Parameters

Response 200

Response 400

Checkouts

The Checkout object

Attributes

List checkouts

Query Parameters

Response 200

Response 401

Create a checkout

Body Parameters

Response 201

Response 400

Response 401

Response 403

Response 409

Retrieve a checkout

Path Parameters

Response 200

Response 401

Response 404

Process a checkout

Path Parameters

Body Parameters

Response 200

Response 400

Response 401

Response 404

Response 409

Deactivate a checkout

Path Parameters

Response 200

Response 401

Response 404

Response 409

Get available payment methods

Path Parameters

Query Parameters

Response 200

Response 400

Response 401

Customers

The Customer object

Attributes

Create a customer

Body Parameters

Response 201

Response 401

Response 403

Response 409

Retrieve a customer

Path Parameters

Response 200

Response 401

Response 403

Response 404

Update a customer

Path Parameters

Body Parameters

Response 200

Response 401

Response 403

Response 404

List payment instruments

Path Parameters

Response 200

Response 401

Response 403

Response 404

Create a payment instrument

Path Parameters

Body Parameters

Response 201