Skip to content
SumUp Developer

API Reference

SumUp’s REST API operates with JSON HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes.

You can experiment and work on your integration in a sandbox that doesn't affect your regular data and doesn't process real transactions. To create a sandbox merchant account visit the dashboard. To use the sandbox when interacting with SumUp APIs create an API key and use it for authentication.

Base URL
https://api.sumup.com

SDKs

The SumUp SDKs reduce the amount of work required to use our REST APIs. SumUp maintains SDKs for PHP, Node.js, Python, and Go.

SDKs

Install SDK
npm install --save @sumup/sdk
go get github.com/sumup/sumup-go
pip install python
composer require sumup/sumup-ecom-php-sdk
cargo add sumup

You can also explore out APIs in Postman using SumUp Developers public collection.

Authentication

The SumUp API uses API keys to authenticate requests. You can view, create, and manage your API keys in the Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Keep your API keys secret and safe. Do not share your API keys or expose them in a publicly accessible areas such as client-side code (browser or apps) or in the GitHub.

All API requests must be made over HTTPS and authenticated. Calls made over plain HTTP or calls without authentication will fail.

Authenticate
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp({ apiKey: 'sup_sk_MvxmLOl0...' });
package main


import (
  sumup "github.com/sumup/sumup-go"
)


func main() {
  client := sumup.NewClient().WithAuth("sup_sk_MvxmLOl0...")
}
from sumup import Sumup


client = SumUp(api_key="sup_sk_MvxmLOl0...")
composer require sumup/sumup-ecom-php-sdk
use sumup::Client;


let client = Client::default().with_authorization("sup_sk_MvxmLOl0...");

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.

Checkout

  • checkout_reference  string

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

  • amount  number

    Amount of the payment.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • id  string

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

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

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Required scopes: payments

Query Parameters

  • checkout_reference  string

Response 200

 []object
 Show attributes
 Close
Attributes
  • checkout_reference  string

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

  • amount  number

    Amount of the payment.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • id  string

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • 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"
  • merchant_name  string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url  string

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

    Example: "https://mysite.com/completed_purchase"
  • 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"
GET /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.list();
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.list()
client := sumup.NewClient()


result, err := client.Checkouts.List(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.checkouts().list().await;
List checkouts response
[
  {
    "checkout_reference": null,
    "amount": 10.1,
    "currency": "EUR",
    "merchant_code": null,
    "description": null,
    "return_url": null,
    "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
    "status": null,
    "date": "2020-02-29T10:56:56+00:00",
    "valid_until": "2020-02-29T10:56:56+00:00",
    "customer_id": "831ff8d4cd5958ab5670",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MDASYTPD"
    },
    "transactions": [
      {
        "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
        "transaction_code": "TEENSK4W2K",
        "amount": 10.1,
        "currency": "EUR",
        "timestamp": "2020-02-29T10:56:56.876Z",
        "status": null,
        "payment_type": null,
        "installments_count": null,
        "merchant_code": "MH4H92C7",
        "vat_amount": 6,
        "tip_amount": 3,
        "entry_mode": null,
        "auth_code": "053201",
        "internal_id": 1763892018
      }
    ],
    "transaction_code": "TEENSK4W2K",
    "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
    "merchant_name": "Sample Merchant",
    "redirect_url": "https://mysite.com/completed_purchase",
    "payment_instrument": {
      "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
    }
  }
]
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.

Required scopes: payments

Body Parameters

  • checkout_reference  string  required

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

  • amount  number  required

    Amount of the payment.

  • currency  string  required

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string  required

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • customer_id  string

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

  • purpose  string
    Options:  CHECKOUT SETUP_RECURRING_PAYMENT

    Purpose of the checkout.

  • id  string

    Unique ID of the checkout resource.

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • redirect_url  string

    Required for APMs and recommended for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the Payment Widget renders 3DS challenge within an iframe instead of performing a full-page redirect.

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

Checkout

  • checkout_reference  string

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

  • amount  number

    Amount of the payment.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • id  string

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
POST /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "checkout_reference": "",
    "amount": 0,
    "currency": "EUR",
    "merchant_code": ""
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.create({
  checkout_reference: "",
  amount: 0,
  currency: "EUR",
  merchant_code: "",
});
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.create(CreateCheckoutBody(
  checkout_reference="",
  amount=0,
  currency="EUR",
  merchant_code="",
))
client := sumup.NewClient()


result, err := client.Checkouts.Create(context.Background(), checkouts.CreateCheckoutBody{
  CheckoutReference: "",
  Amount: 0,
  Currency: "EUR",
  MerchantCode: "",
})
use sumup::Client;


let client = Client::default();


let result = client.checkouts().create(sumup::CreateCheckoutBody {
  checkout_reference: "".to_string(),
  amount: 0,
  currency: "EUR".to_string(),
  merchant_code: "".to_string(),
}).await;
Response
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MDASYTPD"
  },
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "redirect_url": "https://mysite.com/completed_purchase",
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MCNPLE22",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2021-06-29T11:08:36.000+00:00",
  "merchant_name": "My company",
  "merchant_country": "DE",
  "redirect_url": "https://sumup.com",
  "purpose": "CHECKOUT",
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
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.

Required scopes: payments

Path Parameters

  • id  string  required

Response 200

  • checkout_reference  string

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

  • amount  number

    Amount of the payment.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • id  string

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • 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"
  • merchant_name  string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url  string

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

    Example: "https://mysite.com/completed_purchase"
  • 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"
GET /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.get("id");
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.get("id")
client := sumup.NewClient()


result, err := client.Checkouts.Get(context.Background(), "id")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().get(&"id".to_string()).await;
Retrieve a checkout response
{
  "checkout_reference": null,
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": null,
  "description": null,
  "return_url": null,
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": null,
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MDASYTPD"
  },
  "transactions": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": null,
      "auth_code": "053201",
      "internal_id": 1763892018
    }
  ],
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "merchant_name": "Sample Merchant",
  "redirect_url": "https://mysite.com/completed_purchase",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  }
}
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

  • payment_type  string  required
    Options:  card boleto ideal blik bancontact

    Describes the payment method used to attempt processing

  • installments  integer

    Number of installments for deferred payments. Available only to merchant users in Brazil.

  • mandate  object

    Mandate is passed when a card is to be tokenized

     Show attributes
     Close
    Attributes
    • type  string  required
      Options:  recurrent

      Indicates the mandate type

    • user_agent  string  required

      Operating system and web client used by the end-user

    • user_ip  string

      IP address of the end user. Supports IPv4 and IPv6

    Example: {"type":"recurrent","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36","user_ip":"172.217.169.174"}
  • card  object

    Required when payment type is card. Details of the payment card.

     Show attributes
     Close
    Attributes
    • name  string  required

      Name of the cardholder as it appears on the payment card.

      Example: "FIRSTNAME LASTNAME"
    • number  string  required

      Number of the payment card (without spaces).

      Example: "1234567890123456"
    • expiry_year  string  required

      Year from the expiration time of the payment card. Accepted formats are YY and YYYY.

      Example: "2023"
    • expiry_month  string  required
      Options:  01 02 03 04 05 06 07 08 09 10 11 12

      Month from the expiration time of the payment card. Accepted format is MM.

    • cvv  string  required

      Three or four-digit card verification value (security code) of the payment card.

      Example: "123"
    • zip_code  string

      Required five-digit ZIP code. Applicable only to merchant users in the USA.

      Example: "12345"
    • last_4_digits  string  required

      Last 4 digits of the payment card number.

      Example: "3456"
    • type  string  required
      Options:  AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN

      Issuing card network of the payment card.

  • token  string

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

  • customer_id  string

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

  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"

Response 200

  • checkout_reference  string

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

  • amount  number

    Amount of the payment.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • return_url  string

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

  • id  string

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • 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"
  • 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"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • 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"
  • merchant_name  string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url  string

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

    Example: "https://mysite.com/completed_purchase"
  • 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"

Response 202

  • next_step  object

    Required action processing 3D Secure payments.

     Show attributes
     Close
    Attributes
    • url  string

      Where the end user is redirected.

      Example: "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A"
    • method  string

      Method used to complete the redirect.

      Example: "POST"
    • redirect_url  string

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

      Example: "https://mysite.com/completed_purchase"
    • mechanism  []string

      Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.

       Show attributes
       Close
      Attributes
    • payload  object

      Contains parameters essential for form redirection. Number of object keys and their content can vary.

       Show attributes
       Close
      Attributes
      • PaReq  
        Example: "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw=="
      • MD  
        Example: "b1a536c0-29b9-11eb-adc1-0242ac120002"
      • TermUrl  
        Example: "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment"
PUT /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "payment_type": ""
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.process("id", {
  payment_type: "",
});
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.process("id", ProcessCheckoutBody(
  payment_type="",
))
client := sumup.NewClient()


result, err := client.Checkouts.Process(context.Background(), "id", checkouts.ProcessCheckoutBody{
  PaymentType: "",
})
use sumup::Client;


let client = Client::default();


let result = client.checkouts().process(&"id".to_string(), sumup::ProcessCheckoutBody {
  payment_type: "".to_string(),
}).await;
Response
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "return_url": "http://example.com",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MDASYTPD"
  },
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "053201",
      "internal_id": 1763892018
    }
  ],
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
}
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase with token",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "merchant_name": "Sample Merchant",
  "redirect_url": "https://mysite.com/completed_purchase",
  "customer_id": "831ff8d4cd5958ab5670",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "053201",
      "internal_id": 1763892018
    }
  ]
}
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "BRL",
  "merchant_code": "MH4H92C7",
  "description": "Boleto checkout",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2021-07-06T12:34:02.000+00:00",
  "merchant_name": "Sample shop",
  "boleto": {
    "barcode": "34191090081790614310603072340007886840000000200",
    "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
  },
  "redirect_url": "https://website.com",
  "purpose": "CHECKOUT",
  "transactions": [
    {
      "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
      "transaction_code": "TEN3E696NP",
      "merchant_code": "MH4H92C9",
      "amount": 10.1,
      "vat_amount": 6,
      "tip_amount": 3,
      "currency": "BRL",
      "timestamp": "2021-07-06T12:34:16.460+00:00",
      "status": "PENDING",
      "payment_type": "BOLETO",
      "entry_mode": "BOLETO",
      "installments_count": 1,
      "internal_id": 1763892018
    }
  ]
}
{
  "next_step": {
    "url": "https://r3.girogate.de/ti/simideal",
    "method": "GET",
    "payload": {
      "tx": "961473700",
      "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
      "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5"
    },
    "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
    "mechanism": [
      "browser"
    ]
  }
}
{
  "next_step": {
    "url": "https://r3.girogate.de/ti/simbcmc",
    "method": "GET",
    "payload": {
      "tx": "624788471",
      "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
      "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc"
    },
    "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
    "mechanism": [
      "browser"
    ]
  }
}
Checkouts

Deactivate a checkout

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

Required scopes: payments

Path Parameters

  • id  string  required

Response 200

  • checkout_reference  string

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

  • id  string

    Unique ID of the checkout resource.

  • amount  number

    Amount of the payment.

  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • description  string

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

  • purpose  string
    Options:  SETUP_RECURRING_PAYMENT CHECKOUT

    Purpose of the checkout creation initially

  • status  string
    Options:  EXPIRED

    Current status of the checkout.

  • 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"
  • 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

    Merchant name

  • merchant_country  string

    The merchant's country

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • merchant_code  string

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

      Example: "MH4H92C7"
    • vat_amount  number

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

      Example: 6
    • tip_amount  number

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

      Example: 3
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • auth_code  string

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

      Example: "053201"
    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
DELETE /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.deactivate("id");
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.deactivate("id")
client := sumup.NewClient()


result, err := client.Checkouts.Deactivate(context.Background(), "id")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().deactivate(&"id".to_string()).await;
Response
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "amount": 2,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Deletion example",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "merchant_name": "Sample Merchant",
  "transactions": []
}
Checkouts

Get available payment methods

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

Required scopes: payments

Path Parameters

  • merchant_code  string  required
    Example: M1234

Query Parameters

  • amount  number
    Example: 9.99
  • currency  string
    Example: EUR

Response 200

  • available_payment_methods  []object
     Show attributes
     Close
    Attributes
    • id  string  required

      The ID of the payment method.

      Example: "qr_code_pix"
GET /v0.1/merchants/{merchant_code}/payment-methods 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.checkouts.listAvailablePaymentMethods("M1234");
from sumup import Sumup


client = SumUp()


res = sumup.checkouts.list_available_payment_methods("M1234")
client := sumup.NewClient()


result, err := client.Checkouts.ListAvailablePaymentMethods(context.Background(), "M1234")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().list_available_payment_methods(&"M1234".to_string()).await;
Response
{
  "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

Customer

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
The Customer object
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Create a customer

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

Required scopes: payment_instruments

Customer

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
POST /v0.1/customers 
curl https://api.sumup.com/v0.1/customers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "customer_id": "831ff8d4cd5958ab5670"
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.customers.create({
  customer_id: "831ff8d4cd5958ab5670",
});
from sumup import Sumup


client = SumUp()


res = sumup.customers.create(CreateCustomerBody(
  customer_id="831ff8d4cd5958ab5670",
))
client := sumup.NewClient()


result, err := client.Customers.Create(context.Background(), customers.CreateCustomerBody{
  CustomerId: "831ff8d4cd5958ab5670",
})
use sumup::Client;


let client = Client::default();


let result = client.customers().create(sumup::CreateCustomerBody {
  customer_id: "831ff8d4cd5958ab5670".to_string(),
}).await;
Create a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Retrieve a customer

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

Required scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Customer

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
GET /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.customers.get("customer_id");
from sumup import Sumup


client = SumUp()


res = sumup.customers.get("customer_id")
client := sumup.NewClient()


result, err := client.Customers.Get(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().get(&"customer_id".to_string()).await;
Retrieve a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
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.

Required scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Body Parameters

  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • email  string

      Email address of the customer.

      Example: "user@example.com"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id  string

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
PUT /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.customers.update("customer_id", {


});
from sumup import Sumup


client = SumUp()


res = sumup.customers.update("customer_id", UpdateCustomerBody(


))
client := sumup.NewClient()


result, err := client.Customers.Update(context.Background(), "customer_id", customers.UpdateCustomerBody{


})
use sumup::Client;


let client = Client::default();


let result = client.customers().update(&"customer_id".to_string(), sumup::UpdateCustomerBody {


}).await;
Update a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

List payment instruments

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

Required scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Response 200

 []object
 Show attributes
 Close
Attributes
  • token  string

    Unique token identifying the saved payment card for a customer.

  • 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.

  • type  string
    Options:  card

    Type of the payment instrument.

  • 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.

  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • type  string

      Indicates the mandate type

    • status  string

      Mandate status

    • merchant_code  string

      Merchant code which has the mandate

    Example: {"type":"recurrent","status":"active","merchant_code":"MDASYTPD"}
  • created_at  string

    Creation date of payment instrument. Response format expressed according to ISO8601 code.

GET /v0.1/customers/{customer_id}/payment-instruments 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.customers.listPaymentInstruments("customer_id");
from sumup import Sumup


client = SumUp()


res = sumup.customers.list_payment_instruments("customer_id")
client := sumup.NewClient()


result, err := client.Customers.ListPaymentInstruments(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().list_payment_instruments(&"customer_id".to_string()).await;
List payment instruments response
[
  {
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "active": true,
    "type": "card",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MDASYTPD"
    },
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00"
  }
]
Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id  string  required
  • token  string  required
DELETE /v0.1/customers/{customer_id}/payment-instruments/{token} 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.customers.deactivatePaymentInstrument("customer_id", "token");
from sumup import Sumup


client = SumUp()


res = sumup.customers.deactivate_payment_instrument("customer_id", "token")
client := sumup.NewClient()


result, err := client.Customers.DeactivatePaymentInstrument(context.Background(), "customer_id", "token")
use sumup::Client;


let client = Client::default();


let result = client.customers().deactivate_payment_instrument(&"customer_id".to_string(), &"token".to_string()).await;

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

Refund a transaction

Refunds an identified transaction either in full or partially.

Required 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.

POST /v0.1/me/refund/{txn_id} 
curl https://api.sumup.com/v0.1/me/refund/{txn_id} \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.transactions.refund("txn_id", {


});
from sumup import Sumup


client = SumUp()


res = sumup.transactions.refund("txn_id", RefundTransactionBody(


))
client := sumup.NewClient()


result, err := client.Transactions.Refund(context.Background(), "txn_id", transactions.RefundTransactionBody{


})
use sumup::Client;


let client = Client::default();


let result = client.transactions().refund(&"txn_id".to_string(), sumup::RefundTransactionBody {


}).await;
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
Required scopes: transactions.history

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

  • id  string
  • internal_id  string
  • transaction_code  string
  • foreign_transaction_id  string
  • client_transaction_id  string

Response 200

  • id  string

    Unique ID of the transaction.

    Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
  • transaction_code  string

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

    Example: "TEENSK4W2K"
  • amount  number

    Total amount of the transaction.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • 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"
  • status  string
    Options:  SUCCESSFUL CANCELLED FAILED PENDING

    Current status of the transaction.

  • payment_type  string
    Options:  ECOM RECURRING BOLETO

    Payment type used for the transaction.

  • installments_count  integer

    Current number of the installment for deferred payments.

  • merchant_code  string

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

    Example: "MH4H92C7"
  • vat_amount  number

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

    Example: 6
  • tip_amount  number

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

    Example: 3
  • entry_mode  string
    Options:  CUSTOMER_ENTRY BOLETO

    Entry mode of the payment details.

  • auth_code  string

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

    Example: "053201"
  • internal_id  integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary  string

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

  • payouts_total  integer

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

  • payouts_received  integer

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

  • payout_plan  string
    Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

  • username  string

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

  • lat  number

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

  • lon  number

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

  • horizontal_accuracy  number

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

  • simple_payment_type  string
    Options:  MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

    Simple name of the payment type.

  • verification_method  string
    Options:  none signature offline pin online pin offline pin + signature confirmation code verified

    Verification method used for the transaction.

  • 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.

  • local_time  string

    Local date and time of the creation of the transaction.

  • 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.

    • vat_rate  number

      VAT rate applicable to the product.

    • 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).

    • price_with_vat  number

      Price of a single product item with VAT.

    • 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).

    • quantity  number

      Number of product items for the purchase.

    • 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_rates  []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
  • transaction_events  []object

    List of transaction events related to the transaction.

     Show attributes
     Close
    Attributes
    • id  integer

      Unique ID of the transaction event.

    • event_type  string

      Type of the transaction event.

    • status  string

      Status of the transaction event.

    • amount  number

      Amount of the event.

    • due_date  string

      Date when the transaction event is due to occur.

    • date  string

      Date when the transaction event occurred.

    • installment_number  integer

      Consecutive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.

    • timestamp  string

      Date and time of the transaction event.

  • 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.

  • links  []object

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Attributes
  • events  []object

    List of events related to the transaction.

     Show attributes
     Close
    Attributes
    • id  integer

      Unique ID of the transaction event.

    • transaction_id  string

      Unique ID of the transaction.

    • type  string

      Type of the transaction event.

    • status  string

      Status of the transaction event.

    • amount  number

      Amount of the event.

    • timestamp  string

      Date and time of the transaction event.

    • fee_amount  number

      Amount of the fee related to the event.

    • installment_number  integer

      Consecutive number of the installment.

    • deducted_amount  number

      Amount deducted for the event.

    • deducted_fee_amount  number

      Amount of the fee deducted for the event.

  • location  object

    Details of the payment location as received from the payment terminal.

     Show attributes
     Close
    Attributes
    • lat  number

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

    • lon  number

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

    • horizontal_accuracy  number

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

  • tax_enabled  boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v2.1/merchants/{merchant_code}/transactions 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.transactions.get("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.transactions.get("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Transactions.Get(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.transactions().get(&"MC0X0ABC".to_string()).await;
Retrieve a transaction response
{
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "username": null,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "local_time": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": null,
      "total_price": null,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    null
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": null,
      "due_date": null,
      "date": null,
      "installment_number": null,
      "timestamp": null
    }
  ],
  "simple_status": null,
  "links": [
    null
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
}
Transactions

List transactions

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

Required scopes: transactions.history

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

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
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • product_summary  string

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

    • payouts_total  integer

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

    • payouts_received  integer

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

    • payout_plan  string
      Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

    • transaction_id  string

      Unique ID of the transaction.

    • client_transaction_id  string

      Client-specific ID of the transaction.

    • user  string

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

    • type  string
      Options:  PAYMENT REFUND CHARGE_BACK

      Type of the transaction for the registered user specified in the user property.

    • 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.

  • links  []object
     Show attributes
     Close
    Attributes
    • rel  string

      Specifies the relation to the current resource.

    • href  string

      URL for accessing the related resource.

    • type  string

      Specifies the media type of the related resource.

GET /v2.1/merchants/{merchant_code}/transactions/history 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions/history \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.transactions.list("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.transactions.list("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Transactions.List(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.transactions().list(&"MC0X0ABC".to_string()).await;
List transactions response
{
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null
    }
  ],
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ]
}
Transactions

Retrieve a transactionDeprecated

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
Required scopes: transactions.history

Query Parameters

  • id  string
  • internal_id  string
  • transaction_code  string

Response 200

  • id  string

    Unique ID of the transaction.

    Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
  • transaction_code  string

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

    Example: "TEENSK4W2K"
  • amount  number

    Total amount of the transaction.

    Example: 10.1
  • currency  string

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • 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"
  • status  string
    Options:  SUCCESSFUL CANCELLED FAILED PENDING

    Current status of the transaction.

  • payment_type  string
    Options:  ECOM RECURRING BOLETO

    Payment type used for the transaction.

  • installments_count  integer

    Current number of the installment for deferred payments.

  • merchant_code  string

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

    Example: "MH4H92C7"
  • vat_amount  number

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

    Example: 6
  • tip_amount  number

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

    Example: 3
  • entry_mode  string
    Options:  CUSTOMER_ENTRY BOLETO

    Entry mode of the payment details.

  • auth_code  string

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

    Example: "053201"
  • internal_id  integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary  string

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

  • payouts_total  integer

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

  • payouts_received  integer

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

  • payout_plan  string
    Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

  • username  string

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

  • lat  number

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

  • lon  number

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

  • horizontal_accuracy  number

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

  • simple_payment_type  string
    Options:  MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

    Simple name of the payment type.

  • verification_method  string
    Options:  none signature offline pin online pin offline pin + signature confirmation code verified

    Verification method used for the transaction.

  • 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.

  • local_time  string

    Local date and time of the creation of the transaction.

  • 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.

    • vat_rate  number

      VAT rate applicable to the product.

    • 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).

    • price_with_vat  number

      Price of a single product item with VAT.

    • 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).

    • quantity  number

      Number of product items for the purchase.

    • 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_rates  []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
  • transaction_events  []object

    List of transaction events related to the transaction.

     Show attributes
     Close
    Attributes
    • id  integer

      Unique ID of the transaction event.

    • event_type  string

      Type of the transaction event.

    • status  string

      Status of the transaction event.

    • amount  number

      Amount of the event.

    • due_date  string

      Date when the transaction event is due to occur.

    • date  string

      Date when the transaction event occurred.

    • installment_number  integer

      Consecutive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.

    • timestamp  string

      Date and time of the transaction event.

  • 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.

  • links  []object

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Attributes
  • events  []object

    List of events related to the transaction.

     Show attributes
     Close
    Attributes
    • id  integer

      Unique ID of the transaction event.

    • transaction_id  string

      Unique ID of the transaction.

    • type  string

      Type of the transaction event.

    • status  string

      Status of the transaction event.

    • amount  number

      Amount of the event.

    • timestamp  string

      Date and time of the transaction event.

    • fee_amount  number

      Amount of the fee related to the event.

    • installment_number  integer

      Consecutive number of the installment.

    • deducted_amount  number

      Amount deducted for the event.

    • deducted_fee_amount  number

      Amount of the fee deducted for the event.

  • location  object

    Details of the payment location as received from the payment terminal.

     Show attributes
     Close
    Attributes
    • lat  number

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

    • lon  number

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

    • horizontal_accuracy  number

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

  • tax_enabled  boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v0.1/me/transactions 
curl https://api.sumup.com/v0.1/me/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.transactions.getDeprecated();
from sumup import Sumup


client = SumUp()


res = sumup.transactions.get_deprecated()
client := sumup.NewClient()


result, err := client.Transactions.GetDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.transactions().get_deprecated().await;
Retrieve a transaction response
{
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "username": null,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "local_time": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": null,
      "total_price": null,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    null
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": null,
      "due_date": null,
      "date": null,
      "installment_number": null,
      "timestamp": null
    }
  ],
  "simple_status": null,
  "links": [
    null
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
}
Transactions

List transactionsDeprecated

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

Required 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
    • id  string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code  string

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

      Example: "TEENSK4W2K"
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • 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"
    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • installments_count  integer

      Current number of the installment for deferred payments.

    • product_summary  string

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

    • payouts_total  integer

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

    • payouts_received  integer

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

    • payout_plan  string
      Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

    • transaction_id  string

      Unique ID of the transaction.

    • client_transaction_id  string

      Client-specific ID of the transaction.

    • user  string

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

    • type  string
      Options:  PAYMENT REFUND CHARGE_BACK

      Type of the transaction for the registered user specified in the user property.

    • 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.

  • links  []object
     Show attributes
     Close
    Attributes
    • rel  string

      Specifies the relation to the current resource.

    • href  string

      URL for accessing the related resource.

    • type  string

      Specifies the media type of the related resource.

GET /v0.1/me/transactions/history 
curl https://api.sumup.com/v0.1/me/transactions/history \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.transactions.listDeprecated();
from sumup import Sumup


client = SumUp()


res = sumup.transactions.list_deprecated()
client := sumup.NewClient()


result, err := client.Transactions.ListDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


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

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Merchant Account

  • account  object

    Profile information.

     Show attributes
     Close
    Attributes
    • username  string

      Username of the user profile.

    • type  string
      Options:  normal operator

      The role of the user.

  • personal_profile  object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the user

    • last_name  string

      Last name of the user

    • date_of_birth  string

      Date of birth

    • mobile_phone  string

      Mobile phone number

    • address  object

      Details of the registered address.

       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

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • region_code  string

        Region code

      • post_code  string

        Postal code

      • landline  string

        Landline number

      • first_name  string

        undefined

      • last_name  string

        undefined

      • company  string

        undefined

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • iso_code  string

          Country ISO code

        • en_name  string

          Country EN name

        • native_name  string

          Country native name

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code  string

          Postal code

        • offset  number

          UTC offset

        • dst  boolean

          Daylight Saving Time

      • state_id  string

        undefined

    • complete  boolean
  • merchant_profile  object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Unique identifying code of the merchant profile

    • company_name  string

      Company name

    • website  string

      Website

    • legal_type  object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • id  number

        Unique id

      • full_description  string

        Legal type description

      • description  string

        Legal type short description

      • sole_trader  boolean

        Sole trader legal type if true

    • merchant_category_code  string

      Merchant category code

    • mobile_phone  string

      Mobile phone number

    • company_registration_number  string

      Company registration number

    • vat_id  string

      Vat ID

    • permanent_certificate_access_code  string

      Permanent certificate access code (Portugal)

    • nature_and_purpose  string

      Nature and purpose of the business

    • address  object

      Details of the registered address.

       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

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • region_code  string

        Region code

      • post_code  string

        Postal code

      • landline  string

        Landline number

      • first_name  string

        undefined

      • last_name  string

        undefined

      • company  string

        undefined

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • iso_code  string

          Country ISO code

        • en_name  string

          Country EN name

        • native_name  string

          Country native name

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code  string

          Postal code

        • offset  number

          UTC offset

        • dst  boolean

          Daylight Saving Time

      • state_id  string

        undefined

    • business_owners  []object

      Business owners information.

    • doing_business_as  object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • business_name  string

        Doing business as name

      • company_registration_number  string

        Doing business as company registration number

      • vat_id  string

        Doing business as VAT ID

      • website  string

        Doing business as website

      • email  string

        Doing business as email

      • 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

        • region_id  number

          Country region ID

        • region_name  string

          Country region name

        • post_code  string

          Postal code

    • settings  object

      Merchant settings (like "payout_type", "payout_period")

       Show attributes
       Close
      Attributes
      • tax_enabled  boolean

        Whether to show tax in receipts (saved per transaction)

      • payout_type  string

        Payout type

      • payout_period  string

        Payout frequency

      • payout_on_demand_available  boolean

        Whether merchant can edit payouts on demand

      • payout_on_demand  boolean

        Whether merchant will receive payouts on demand

      • printers_enabled  boolean

        Whether to show printers in mobile app

      • payout_instrument  string

        Payout Instrument

      • moto_payment  string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • stone_merchant_code  string

        Stone merchant code

      • daily_payout_email  boolean

        Whether merchant will receive daily payout emails

      • monthly_payout_email  boolean

        Whether merchant will receive monthly payout emails

      • gross_settlement  boolean

        Whether merchant has gross settlement enabled

    • vat_rates  object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • id  number

        Internal ID

      • description  string

        Description

      • rate  number

        Rate

      • ordering  number

        Ordering

      • country  string

        Country ISO code

    • locale  string

      Merchant locale (for internal usage only)

    • bank_accounts  []object
       Show attributes
       Close
      Attributes
      • bank_code  string

        Bank code

      • branch_code  string

        Branch code

      • swift  string

        SWIFT code

      • account_number  string

        Account number

      • iban  string

        IBAN

      • account_type  string

        Type of the account

      • account_category  string

        Account category - business or personal

      • account_holder_name  string
      • status  string

        Status in the verification process

      • primary  boolean

        The primary bank account is the one used for payouts

      • created_at  string

        Creation date of the bank account

      • bank_name  string

        Bank name

    • extdev  boolean

      True if the merchant is extdev

    • payout_zone_migrated  boolean

      True if the payout zone of this merchant is migrated

    • country  string

      Merchant country code formatted according to ISO3166-1 alpha-2 (for internal usage only)

  • app_settings  object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • checkout_preference  string

      Checkout preference

    • include_vat  boolean

      Include vat.

    • manual_entry_tutorial  boolean

      Manual entry tutorial.

    • mobile_payment_tutorial  boolean

      Mobile payment tutorial.

    • tax_enabled  boolean

      Tax enabled.

    • mobile_payment  string

      Mobile payment.

    • reader_payment  string

      Reader payment.

    • cash_payment  string

      Cash payment.

    • advanced_mode  string

      Advanced mode.

    • expected_max_transaction_amount  number

      Expected max transaction amount.

    • manual_entry  string

      Manual entry.

    • terminal_mode_tutorial  boolean

      Terminal mode tutorial.

    • tipping  string

      Tipping.

    • tip_rates  []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • barcode_scanner  string

      Barcode scanner.

    • referral  string

      Referral.

  • permissions  object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean

      Create MOTO payments

    • full_transaction_history_view  boolean

      Can view full merchant transaction history

    • refund_transactions  boolean

      Refund transactions

    • create_referral  boolean

      Create referral

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

Get settings

Retrieves merchant settings.

Required scopes: user.payout-settings

Response 200

  • tax_enabled  boolean

    Whether to show tax in receipts (saved per transaction)

  • payout_type  string

    Payout type

  • payout_period  string

    Payout frequency

  • payout_on_demand_available  boolean

    Whether merchant can edit payouts on demand

  • payout_on_demand  boolean

    Whether merchant will receive payouts on demand

  • printers_enabled  boolean

    Whether to show printers in mobile app

  • payout_instrument  string

    Payout Instrument

  • moto_payment  string
    Options:  UNAVAILABLE ENFORCED ON OFF

    Whether merchant can make MOTO payments

  • stone_merchant_code  string

    Stone merchant code

  • daily_payout_email  boolean

    Whether merchant will receive daily payout emails

  • monthly_payout_email  boolean

    Whether merchant will receive monthly payout emails

  • gross_settlement  boolean

    Whether merchant has gross settlement enabled

GET /v0.1/me/merchant-profile/settings 
curl https://api.sumup.com/v0.1/me/merchant-profile/settings \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.getSettings();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.get_settings()
client := sumup.NewClient()


result, err := client.Merchant.GetSettings(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().get_settings().await;
Get settings response
{
  "tax_enabled": null,
  "payout_type": null,
  "payout_period": null,
  "payout_on_demand_available": null,
  "payout_on_demand": null,
  "printers_enabled": null,
  "payout_instrument": null,
  "moto_payment": null,
  "stone_merchant_code": null,
  "daily_payout_email": null,
  "monthly_payout_email": null,
  "gross_settlement": null
}
Merchant

List bank accounts

Retrieves bank accounts of the merchant.

Required scopes: user.payout-settings user.profile user.profile_readonly

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

  • primary  boolean

Response 200

 []object
 Show attributes
 Close
Attributes
  • bank_code  string

    Bank code

  • branch_code  string

    Branch code

  • swift  string

    SWIFT code

  • account_number  string

    Account number

  • iban  string

    IBAN

  • account_type  string

    Type of the account

  • account_category  string

    Account category - business or personal

  • account_holder_name  string
  • status  string

    Status in the verification process

  • primary  boolean

    The primary bank account is the one used for payouts

  • created_at  string

    Creation date of the bank account

  • bank_name  string

    Bank name

GET /v1.1/merchants/{merchant_code}/bank-accounts 
curl https://api.sumup.com/v1.1/merchants/{merchant_code}/bank-accounts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.listBankAccounts("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.merchant.list_bank_accounts("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Merchant.ListBankAccounts(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.merchant().list_bank_accounts(&"MC0X0ABC".to_string()).await;
List bank accounts response
[
  {
    "bank_code": null,
    "branch_code": null,
    "swift": null,
    "account_number": null,
    "iban": null,
    "account_type": null,
    "account_category": null,
    "account_holder_name": null,
    "status": null,
    "primary": null,
    "created_at": null,
    "bank_name": null
  }
]
Merchant

Retrieve a profileDeprecated

Returns user profile information.

Required scopes: user.profile user.profile_readonly

Query Parameters

  • include[]  []string

Merchant Account

  • account  object

    Profile information.

     Show attributes
     Close
    Attributes
    • username  string

      Username of the user profile.

    • type  string
      Options:  normal operator

      The role of the user.

  • personal_profile  object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • first_name  string

      First name of the user

    • last_name  string

      Last name of the user

    • date_of_birth  string

      Date of birth

    • mobile_phone  string

      Mobile phone number

    • address  object

      Details of the registered address.

       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

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • region_code  string

        Region code

      • post_code  string

        Postal code

      • landline  string

        Landline number

      • first_name  string

        undefined

      • last_name  string

        undefined

      • company  string

        undefined

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • iso_code  string

          Country ISO code

        • en_name  string

          Country EN name

        • native_name  string

          Country native name

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code  string

          Postal code

        • offset  number

          UTC offset

        • dst  boolean

          Daylight Saving Time

      • state_id  string

        undefined

    • complete  boolean
  • merchant_profile  object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Unique identifying code of the merchant profile

    • company_name  string

      Company name

    • website  string

      Website

    • legal_type  object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • id  number

        Unique id

      • full_description  string

        Legal type description

      • description  string

        Legal type short description

      • sole_trader  boolean

        Sole trader legal type if true

    • merchant_category_code  string

      Merchant category code

    • mobile_phone  string

      Mobile phone number

    • company_registration_number  string

      Company registration number

    • vat_id  string

      Vat ID

    • permanent_certificate_access_code  string

      Permanent certificate access code (Portugal)

    • nature_and_purpose  string

      Nature and purpose of the business

    • address  object

      Details of the registered address.

       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

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • region_code  string

        Region code

      • post_code  string

        Postal code

      • landline  string

        Landline number

      • first_name  string

        undefined

      • last_name  string

        undefined

      • company  string

        undefined

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • iso_code  string

          Country ISO code

        • en_name  string

          Country EN name

        • native_name  string

          Country native name

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code  string

          Postal code

        • offset  number

          UTC offset

        • dst  boolean

          Daylight Saving Time

      • state_id  string

        undefined

    • business_owners  []object

      Business owners information.

    • doing_business_as  object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • business_name  string

        Doing business as name

      • company_registration_number  string

        Doing business as company registration number

      • vat_id  string

        Doing business as VAT ID

      • website  string

        Doing business as website

      • email  string

        Doing business as email

      • 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

        • region_id  number

          Country region ID

        • region_name  string

          Country region name

        • post_code  string

          Postal code

    • settings  object

      Merchant settings (like "payout_type", "payout_period")

       Show attributes
       Close
      Attributes
      • tax_enabled  boolean

        Whether to show tax in receipts (saved per transaction)

      • payout_type  string

        Payout type

      • payout_period  string

        Payout frequency

      • payout_on_demand_available  boolean

        Whether merchant can edit payouts on demand

      • payout_on_demand  boolean

        Whether merchant will receive payouts on demand

      • printers_enabled  boolean

        Whether to show printers in mobile app

      • payout_instrument  string

        Payout Instrument

      • moto_payment  string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • stone_merchant_code  string

        Stone merchant code

      • daily_payout_email  boolean

        Whether merchant will receive daily payout emails

      • monthly_payout_email  boolean

        Whether merchant will receive monthly payout emails

      • gross_settlement  boolean

        Whether merchant has gross settlement enabled

    • vat_rates  object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • id  number

        Internal ID

      • description  string

        Description

      • rate  number

        Rate

      • ordering  number

        Ordering

      • country  string

        Country ISO code

    • locale  string

      Merchant locale (for internal usage only)

    • bank_accounts  []object
       Show attributes
       Close
      Attributes
      • bank_code  string

        Bank code

      • branch_code  string

        Branch code

      • swift  string

        SWIFT code

      • account_number  string

        Account number

      • iban  string

        IBAN

      • account_type  string

        Type of the account

      • account_category  string

        Account category - business or personal

      • account_holder_name  string
      • status  string

        Status in the verification process

      • primary  boolean

        The primary bank account is the one used for payouts

      • created_at  string

        Creation date of the bank account

      • bank_name  string

        Bank name

    • extdev  boolean

      True if the merchant is extdev

    • payout_zone_migrated  boolean

      True if the payout zone of this merchant is migrated

    • country  string

      Merchant country code formatted according to ISO3166-1 alpha-2 (for internal usage only)

  • app_settings  object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • checkout_preference  string

      Checkout preference

    • include_vat  boolean

      Include vat.

    • manual_entry_tutorial  boolean

      Manual entry tutorial.

    • mobile_payment_tutorial  boolean

      Mobile payment tutorial.

    • tax_enabled  boolean

      Tax enabled.

    • mobile_payment  string

      Mobile payment.

    • reader_payment  string

      Reader payment.

    • cash_payment  string

      Cash payment.

    • advanced_mode  string

      Advanced mode.

    • expected_max_transaction_amount  number

      Expected max transaction amount.

    • manual_entry  string

      Manual entry.

    • terminal_mode_tutorial  boolean

      Terminal mode tutorial.

    • tipping  string

      Tipping.

    • tip_rates  []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • barcode_scanner  string

      Barcode scanner.

    • referral  string

      Referral.

  • permissions  object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean

      Create MOTO payments

    • full_transaction_history_view  boolean

      Can view full merchant transaction history

    • refund_transactions  boolean

      Refund transactions

    • create_referral  boolean

      Create referral

GET /v0.1/me 
curl https://api.sumup.com/v0.1/me \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.get();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.get()
client := sumup.NewClient()


result, err := client.Merchant.Get(context.Background())
use sumup::Client;


let client = Client::default();


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

Retrieve a personal profileDeprecated

Retrieves personal profile data.

Required scopes: user.profile user.profile_readonly

Response 200

  • first_name  string

    First name of the user

  • last_name  string

    Last name of the user

  • date_of_birth  string

    Date of birth

  • mobile_phone  string

    Mobile phone number

  • address  object

    Details of the registered address.

     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

    • region_id  number

      Country region id

    • region_name  string

      Region name

    • region_code  string

      Region code

    • post_code  string

      Postal code

    • landline  string

      Landline number

    • first_name  string

      undefined

    • last_name  string

      undefined

    • company  string

      undefined

    • country_details  object

      Country Details

       Show attributes
       Close
      Attributes
      • currency  string

        Currency ISO 4217 code

      • iso_code  string

        Country ISO code

      • en_name  string

        Country EN name

      • native_name  string

        Country native name

    • timeoffset_details  object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • post_code  string

        Postal code

      • offset  number

        UTC offset

      • dst  boolean

        Daylight Saving Time

    • state_id  string

      undefined

  • complete  boolean
GET /v0.1/me/personal-profile 
curl https://api.sumup.com/v0.1/me/personal-profile \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.getPersonalProfile();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.get_personal_profile()
client := sumup.NewClient()


result, err := client.Merchant.GetPersonalProfile(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().get_personal_profile().await;
Retrieve a personal profile response
{
  "first_name": null,
  "last_name": null,
  "date_of_birth": null,
  "mobile_phone": null,
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "region_id": null,
    "region_name": null,
    "region_code": null,
    "post_code": null,
    "landline": null,
    "first_name": null,
    "last_name": null,
    "company": null,
    "country_details": {
      "currency": null,
      "iso_code": null,
      "en_name": null,
      "native_name": null
    },
    "timeoffset_details": {
      "post_code": null,
      "offset": null,
      "dst": null
    },
    "state_id": null
  },
  "complete": null
}
Merchant

Retrieve a merchant profileDeprecated

Retrieves merchant profile data.

Required scopes: user.profile user.profile_readonly

Response 200

  • merchant_code  string

    Unique identifying code of the merchant profile

  • company_name  string

    Company name

  • website  string

    Website

  • legal_type  object

    Id of the legal type of the merchant profile

     Show attributes
     Close
    Attributes
    • id  number

      Unique id

    • full_description  string

      Legal type description

    • description  string

      Legal type short description

    • sole_trader  boolean

      Sole trader legal type if true

  • merchant_category_code  string

    Merchant category code

  • mobile_phone  string

    Mobile phone number

  • company_registration_number  string

    Company registration number

  • vat_id  string

    Vat ID

  • permanent_certificate_access_code  string

    Permanent certificate access code (Portugal)

  • nature_and_purpose  string

    Nature and purpose of the business

  • address  object

    Details of the registered address.

     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

    • region_id  number

      Country region id

    • region_name  string

      Region name

    • region_code  string

      Region code

    • post_code  string

      Postal code

    • landline  string

      Landline number

    • first_name  string

      undefined

    • last_name  string

      undefined

    • company  string

      undefined

    • country_details  object

      Country Details

       Show attributes
       Close
      Attributes
      • currency  string

        Currency ISO 4217 code

      • iso_code  string

        Country ISO code

      • en_name  string

        Country EN name

      • native_name  string

        Country native name

    • timeoffset_details  object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • post_code  string

        Postal code

      • offset  number

        UTC offset

      • dst  boolean

        Daylight Saving Time

    • state_id  string

      undefined

  • business_owners  []object

    Business owners information.

  • doing_business_as  object

    Doing Business As information

     Show attributes
     Close
    Attributes
    • business_name  string

      Doing business as name

    • company_registration_number  string

      Doing business as company registration number

    • vat_id  string

      Doing business as VAT ID

    • website  string

      Doing business as website

    • email  string

      Doing business as email

    • 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

      • region_id  number

        Country region ID

      • region_name  string

        Country region name

      • post_code  string

        Postal code

  • settings  object

    Merchant settings (like "payout_type", "payout_period")

     Show attributes
     Close
    Attributes
    • tax_enabled  boolean

      Whether to show tax in receipts (saved per transaction)

    • payout_type  string

      Payout type

    • payout_period  string

      Payout frequency

    • payout_on_demand_available  boolean

      Whether merchant can edit payouts on demand

    • payout_on_demand  boolean

      Whether merchant will receive payouts on demand

    • printers_enabled  boolean

      Whether to show printers in mobile app

    • payout_instrument  string

      Payout Instrument

    • moto_payment  string
      Options:  UNAVAILABLE ENFORCED ON OFF

      Whether merchant can make MOTO payments

    • stone_merchant_code  string

      Stone merchant code

    • daily_payout_email  boolean

      Whether merchant will receive daily payout emails

    • monthly_payout_email  boolean

      Whether merchant will receive monthly payout emails

    • gross_settlement  boolean

      Whether merchant has gross settlement enabled

  • vat_rates  object

    Merchant VAT rates

     Show attributes
     Close
    Attributes
    • id  number

      Internal ID

    • description  string

      Description

    • rate  number

      Rate

    • ordering  number

      Ordering

    • country  string

      Country ISO code

  • locale  string

    Merchant locale (for internal usage only)

  • bank_accounts  []object
     Show attributes
     Close
    Attributes
    • bank_code  string

      Bank code

    • branch_code  string

      Branch code

    • swift  string

      SWIFT code

    • account_number  string

      Account number

    • iban  string

      IBAN

    • account_type  string

      Type of the account

    • account_category  string

      Account category - business or personal

    • account_holder_name  string
    • status  string

      Status in the verification process

    • primary  boolean

      The primary bank account is the one used for payouts

    • created_at  string

      Creation date of the bank account

    • bank_name  string

      Bank name

  • extdev  boolean

    True if the merchant is extdev

  • payout_zone_migrated  boolean

    True if the payout zone of this merchant is migrated

  • country  string

    Merchant country code formatted according to ISO3166-1 alpha-2 (for internal usage only)

GET /v0.1/me/merchant-profile 
curl https://api.sumup.com/v0.1/me/merchant-profile \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.getMerchantProfile();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.get_merchant_profile()
client := sumup.NewClient()


result, err := client.Merchant.GetMerchantProfile(context.Background())
use sumup::Client;


let client = Client::default();


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

List bank accountsDeprecated

Retrieves bank accounts of the merchant.

Required scopes: user.payout-settings user.profile user.profile_readonly

Query Parameters

  • primary  boolean

Response 200

 []object
 Show attributes
 Close
Attributes
  • bank_code  string

    Bank code

  • branch_code  string

    Branch code

  • swift  string

    SWIFT code

  • account_number  string

    Account number

  • iban  string

    IBAN

  • account_type  string

    Type of the account

  • account_category  string

    Account category - business or personal

  • account_holder_name  string
  • status  string

    Status in the verification process

  • primary  boolean

    The primary bank account is the one used for payouts

  • created_at  string

    Creation date of the bank account

  • bank_name  string

    Bank name

GET /v0.1/me/merchant-profile/bank-accounts 
curl https://api.sumup.com/v0.1/me/merchant-profile/bank-accounts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.listBankAccountsDeprecated();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.list_bank_accounts_deprecated()
client := sumup.NewClient()


result, err := client.Merchant.ListBankAccountsDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().list_bank_accounts_deprecated().await;
List bank accounts response
[
  {
    "bank_code": null,
    "branch_code": null,
    "swift": null,
    "account_number": null,
    "iban": null,
    "account_type": null,
    "account_category": null,
    "account_holder_name": null,
    "status": null,
    "primary": null,
    "created_at": null,
    "bank_name": null
  }
]
Merchant

Retrieve DBADeprecated

Retrieves Doing Business As profile.

Required scopes: user.profile user.profile_readonly

Response 200

  • business_name  string

    Doing business as name

  • company_registration_number  string

    Doing business as company registration number

  • vat_id  string

    Doing business as VAT ID

  • website  string

    Doing business as website

  • email  string

    Doing business as email

  • 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

    • region_id  number

      Country region ID

    • region_name  string

      Country region name

    • post_code  string

      Postal code

GET /v0.1/me/merchant-profile/doing-business-as 
curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchant.getDoingBusinessAs();
from sumup import Sumup


client = SumUp()


res = sumup.merchant.get_doing_business_as()
client := sumup.NewClient()


result, err := client.Merchant.GetDoingBusinessAs(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().get_doing_business_as().await;
Retrieve DBA response
{
  "business_name": null,
  "company_registration_number": null,
  "vat_id": null,
  "website": null,
  "email": null,
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "region_id": null,
    "region_name": null,
    "post_code": null
  }
}

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.

The Financial Payouts object

Financial Payouts

 []object
 Show attributes
 Close
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.

Required scopes: user.profile user.profile_readonly

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

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

Financial Payouts

 []object
 Show attributes
 Close
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
GET /v1.0/merchants/{merchant_code}/payouts 
curl https://api.sumup.com/v1.0/merchants/{merchant_code}/payouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.payouts.list("MC0X0ABC", "start_date", "end_date");
from sumup import Sumup


client = SumUp()


res = sumup.payouts.list("MC0X0ABC", "start_date", "end_date")
client := sumup.NewClient()


result, err := client.Payouts.List(context.Background(), "MC0X0ABC", "start_date", "end_date")
use sumup::Client;


let client = Client::default();


let result = client.payouts().list(&"MC0X0ABC".to_string(), &"start_date".to_string(), &"end_date".to_string()).await;
List payouts response
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]
Payouts

List payoutsDeprecated

Lists ordered payouts for the merchant profile.

Required scopes: user.profile user.profile_readonly

Query Parameters

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

Financial Payouts

 []object
 Show attributes
 Close
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
GET /v0.1/me/financials/payouts 
curl https://api.sumup.com/v0.1/me/financials/payouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.payouts.listDeprecated("start_date", "end_date");
from sumup import Sumup


client = SumUp()


res = sumup.payouts.list_deprecated("start_date", "end_date")
client := sumup.NewClient()


result, err := client.Payouts.ListDeprecated(context.Background(), "start_date", "end_date")
use sumup::Client;


let client = Client::default();


let result = client.payouts().list_deprecated(&"start_date".to_string(), &"end_date".to_string()).await;
List payouts response
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]

Receipts

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

The Receipt object

Receipt

  • transaction_data  object

    Transaction information.

     Show attributes
     Close
    Attributes
    • transaction_code  string

      Transaction code.

    • amount  string

      Transaction amount.

    • vat_amount  string

      Transaction VAT amount.

    • tip_amount  string

      Tip amount (included in transaction amount).

    • currency  string

      Transaction currency.

    • timestamp  string

      Time created at.

    • status  string

      Transaction processing status.

    • payment_type  string

      Transaction type.

    • entry_mode  string

      Transaction entry mode.

    • verification_method  string

      Cardholder verification method.

    • card  object
       Show attributes
       Close
      Attributes
      • last_4_digits  string

        Card last 4 digits.

      • type  string

        Card Scheme.

    • installments_count  integer

      Number of installments.

    • products  []object

      Products

       Show attributes
       Close
      Attributes
      • name  string

        Product name.

      • description  string

        Product description.

      • price  number

        Product price.

      • quantity  integer

        Product quantity.

      • total_price  number

        Quantity x product price.

    • vat_rates  []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross  number

        Gross

      • net  number

        Net

      • rate  number

        Rate

      • vat  number

        Vat

    • events  []object

      Events

       Show attributes
       Close
      Attributes
      • id  integer

        Unique ID of the transaction event.

      • transaction_id  string

        Unique ID of the transaction.

      • type  string

        Type of the transaction event.

      • status  string

        Status of the transaction event.

      • amount  number

        Amount of the event.

      • timestamp  string

        Date and time of the transaction event.

      • receipt_no  string
    • receipt_no  string

      Receipt number

  • merchant_data  object

    Receipt merchant data

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

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Path Parameters

  • id  string  required

Query Parameters

  • mid  string  required
  • tx_event_id  integer

Receipt

  • transaction_data  object

    Transaction information.

     Show attributes
     Close
    Attributes
    • transaction_code  string

      Transaction code.

    • amount  string

      Transaction amount.

    • vat_amount  string

      Transaction VAT amount.

    • tip_amount  string

      Tip amount (included in transaction amount).

    • currency  string

      Transaction currency.

    • timestamp  string

      Time created at.

    • status  string

      Transaction processing status.

    • payment_type  string

      Transaction type.

    • entry_mode  string

      Transaction entry mode.

    • verification_method  string

      Cardholder verification method.

    • card  object
       Show attributes
       Close
      Attributes
      • last_4_digits  string

        Card last 4 digits.

      • type  string

        Card Scheme.

    • installments_count  integer

      Number of installments.

    • products  []object

      Products

       Show attributes
       Close
      Attributes
      • name  string

        Product name.

      • description  string

        Product description.

      • price  number

        Product price.

      • quantity  integer

        Product quantity.

      • total_price  number

        Quantity x product price.

    • vat_rates  []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross  number

        Gross

      • net  number

        Net

      • rate  number

        Rate

      • vat  number

        Vat

    • events  []object

      Events

       Show attributes
       Close
      Attributes
      • id  integer

        Unique ID of the transaction event.

      • transaction_id  string

        Unique ID of the transaction.

      • type  string

        Type of the transaction event.

      • status  string

        Status of the transaction event.

      • amount  number

        Amount of the event.

      • timestamp  string

        Date and time of the transaction event.

      • receipt_no  string
    • receipt_no  string

      Receipt number

  • merchant_data  object

    Receipt merchant data

     Show attributes
     Close
    Attributes
    • merchant_profile  object
       Show attributes
       Close
      Attributes
      • merchant_code  string
      • business_name  string
      • email  string
      • address  object
         Show attributes
         Close
        Attributes
        • address_line1  string
        • city  string
        • country  string
        • country_en_name  string
        • country_native_name  string
        • post_code  string
        • landline  string
    • locale  string
  • emv_data  object
     Show attributes
     Close
    Attributes
  • acquirer_data  object
     Show attributes
     Close
    Attributes
    • tid  string
    • authorization_code  string
    • return_code  string
    • local_time  string
GET /v1.1/receipts/{id} 
curl https://api.sumup.com/v1.1/receipts/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.receipts.get("id", "mid");
from sumup import Sumup


client = SumUp()


res = sumup.receipts.get("id", "mid")
client := sumup.NewClient()


result, err := client.Receipts.Get(context.Background(), "id", "mid")
use sumup::Client;


let client = Client::default();


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

Subaccounts

Endpoints for managing merchant sub-accounts (operators).

The object

Operator account for a merchant.

Attributes

  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
The object
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

List operatorsDeprecated

Returns list of operators for currently authorized user's merchant.

Query Parameters

  • query  string
  • include_primary  boolean

Response 200

 []object
 Show attributes
 Close
Attributes
  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
GET /v0.1/me/accounts 
curl https://api.sumup.com/v0.1/me/accounts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.subaccounts.listSubAccounts();
from sumup import Sumup


client = SumUp()


res = sumup.subaccounts.list_sub_accounts()
client := sumup.NewClient()


result, err := client.Subaccounts.ListSubAccounts(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().list_sub_accounts().await;
List operators response
[
  {
    "id": 0,
    "username": "operator1@mydomain.com",
    "nickname": "Operator 1",
    "disabled": false,
    "created_at": "",
    "updated_at": "",
    "permissions": {
      "create_moto_payments": false,
      "create_referral": false,
      "full_transaction_history_view": false,
      "refund_transactions": false,
      "admin": false
    },
    "account_type": ""
  }
]
Subaccounts

Create an operatorDeprecated

Creates new operator for currently authorized users' merchant.

Body Parameters

  • username  string  required
    Example: "operator1@mydomain.com"
  • password  string  required
    Example: "correct horse batter staple"
  • nickname  string
    Example: "Operator 1"
  • permissions  object
     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean
    • create_referral  boolean
    • full_transaction_history_view  boolean
    • refund_transactions  boolean

Response 200

  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
POST /v0.1/me/accounts 
curl https://api.sumup.com/v0.1/me/accounts \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "username": "operator1@mydomain.com",
    "password": "correct horse batter staple"
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.subaccounts.createSubAccount({
  username: "operator1@mydomain.com",
  password: "correct horse batter staple",
});
from sumup import Sumup


client = SumUp()


res = sumup.subaccounts.create_sub_account(CreateSubAccountBody(
  username="operator1@mydomain.com",
  password="correct horse batter staple",
))
client := sumup.NewClient()


result, err := client.Subaccounts.CreateSubAccount(context.Background(), subaccounts.CreateSubAccountBody{
  Username: "operator1@mydomain.com",
  Password: "correct horse batter staple",
})
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().create_sub_account(sumup::CreateSubAccountBody {
  username: "operator1@mydomain.com".to_string(),
  password: "correct horse batter staple".to_string(),
}).await;
Create an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Retrieve an operatorDeprecated

Returns specific operator.

Path Parameters

  • operator_id  integer  required

Response 200

  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
GET /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.subaccounts.compatGetOperator("operator_id");
from sumup import Sumup


client = SumUp()


res = sumup.subaccounts.compat_get_operator("operator_id")
client := sumup.NewClient()


result, err := client.Subaccounts.CompatGetOperator(context.Background(), "operator_id")
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().compat_get_operator(&"operator_id".to_string()).await;
Retrieve an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Update an operatorDeprecated

Updates operator. If the operator was disabled and their password is updated they will be unblocked.

Path Parameters

  • operator_id  integer  required

Body Parameters

  • password  string
    Example: "correct horse batter staple"
  • username  string
  • disabled  boolean
  • nickname  string
    Example: "Operator 1"
  • permissions  object
     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean
    • create_referral  boolean
    • full_transaction_history_view  boolean
    • refund_transactions  boolean

Response 200

  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
PUT /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.subaccounts.updateSubAccount("operator_id", {


});
from sumup import Sumup


client = SumUp()


res = sumup.subaccounts.update_sub_account("operator_id", UpdateSubAccountBody(


))
client := sumup.NewClient()


result, err := client.Subaccounts.UpdateSubAccount(context.Background(), "operator_id", subaccounts.UpdateSubAccountBody{


})
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().update_sub_account(&"operator_id".to_string(), sumup::UpdateSubAccountBody {


}).await;
Update an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Disable an operator.Deprecated

Disable the specified operator for the merchant account.

Path Parameters

  • operator_id  integer  required

Response 200

  • id  integer  required
  • username  string  required
    Example: "operator1@mydomain.com"
  • nickname  string
    Example: "Operator 1"
  • disabled  boolean  required
  • created_at  string  required

    The timestamp of when the operator was created.

  • updated_at  string  required

    The timestamp of when the operator was last updated.

  • permissions  object  required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
    • admin  boolean  required
  • account_type  string  required
    Options:  operator normal
DELETE /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.subaccounts.deactivateSubAccount("operator_id");
from sumup import Sumup


client = SumUp()


res = sumup.subaccounts.deactivate_sub_account("operator_id")
client := sumup.NewClient()


result, err := client.Subaccounts.DeactivateSubAccount(context.Background(), "operator_id")
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().deactivate_sub_account(&"operator_id".to_string()).await;
Disable an operator. response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}

MembershipsPreview feature

Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.

The Membership object

A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.

Membership

  • id  string  required

    ID of the membership.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • resource_id  string  required

    ID of the resource the membership is in.

    Example: "M2DDT39A"
  • type  string  required

    The kind of the membership resource. Possible values are:

    • merchant - merchant account(s)
    • organization - organization(s)
    Example: "merchant"
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at  string  required

    The timestamp of when the membership was created.

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

    The timestamp of when the membership was last updated.

    Example: "2023-01-20T15:16:17Z"
  • invite  object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email  string  required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • status  string  required

    The status of the membership.

  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • resource  object  required

    Information about the resource the membership is in.

     Show attributes
     Close
    Resource
    • id  string  required

      ID of the resource the membership is in.

      Example: "M2DDT39A"
    • type  string  required

      The kind of the membership resource. Possible values are:

      • merchant - merchant account(s)
      • organization - organization(s)
      Example: "merchant"
    • name  string  required

      Display name of the resource.

      Example: "Acme Corp"
    • logo  string

      Logo fo the resource.

      Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
    • created_at  string  required

      The timestamp of when the membership resource was created.

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

      The timestamp of when the membership resource was last updated.

      Example: "2023-01-20T15:16:17Z"
    • attributes  object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
The Membership object
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "resource_id": "M2DDT39A",
  "type": "merchant",
  "roles": [
    "role_admin"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z",
  "invite": {
    "email": "boaty.mcboatface@sumup.com",
    "expires_at": "2023-01-20T15:16:17Z"
  },
  "status": "",
  "metadata": {},
  "attributes": {},
  "resource": {
    "id": "M2DDT39A",
    "type": "merchant",
    "name": "Acme Corp",
    "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
    "created_at": "2023-01-20T15:16:17Z",
    "updated_at": "2023-01-20T15:16:17Z",
    "attributes": {}
  }
}
Memberships

List memberships

List memberships of the current user.

Query Parameters

  • offset  integer
    0
  • limit  integer
    Example: 10
  • kind  string
    Example: merchant
  • resource.attributes.sandbox  boolean
  • resource.name  string

Response 200

  • items  []object  required
     Show attributes
     Close
    Membership
    • id  string  required

      ID of the membership.

      Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • resource_id  string  required

      ID of the resource the membership is in.

      Example: "M2DDT39A"
    • type  string  required

      The kind of the membership resource. Possible values are:

      • merchant - merchant account(s)
      • organization - organization(s)
      Example: "merchant"
    • roles  []string  required

      User's roles.

       Show attributes
       Close
      Attributes
    • permissions  []string  required

      User's permissions.

       Show attributes
       Close
      Attributes
    • created_at  string  required

      The timestamp of when the membership was created.

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

      The timestamp of when the membership was last updated.

      Example: "2023-01-20T15:16:17Z"
    • invite  object

      Pending invitation for membership.

       Show attributes
       Close
      Invite
      • email  string  required

        Email address of the invited user.

        Example: "boaty.mcboatface@sumup.com"
      • expires_at  string  required
        Example: "2023-01-20T15:16:17Z"
    • status  string  required

      The status of the membership.

    • metadata  object

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

       Show attributes
       Close
      Attributes
      Example: {}
    • attributes  object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
    • resource  object  required

      Information about the resource the membership is in.

       Show attributes
       Close
      Resource
      • id  string  required

        ID of the resource the membership is in.

        Example: "M2DDT39A"
      • type  string  required

        The kind of the membership resource. Possible values are:

        • merchant - merchant account(s)
        • organization - organization(s)
        Example: "merchant"
      • name  string  required

        Display name of the resource.

        Example: "Acme Corp"
      • logo  string

        Logo fo the resource.

        Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
      • created_at  string  required

        The timestamp of when the membership resource was created.

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

        The timestamp of when the membership resource was last updated.

        Example: "2023-01-20T15:16:17Z"
      • attributes  object

        Object attributes that are modifiable only by SumUp applications.

         Show attributes
         Close
        Attributes
        Example: {}
  • total_count  integer  required
    Example: 3
GET /v0.1/memberships 
curl https://api.sumup.com/v0.1/memberships \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.memberships.list();
from sumup import Sumup


client = SumUp()


res = sumup.memberships.list()
client := sumup.NewClient()


result, err := client.Memberships.List(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.memberships().list().await;
List memberships response
{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "resource_id": "M2DDT39A",
      "type": "merchant",
      "roles": [
        "role_admin"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z",
      "invite": {
        "email": "boaty.mcboatface@sumup.com",
        "expires_at": "2023-01-20T15:16:17Z"
      },
      "status": "",
      "metadata": {},
      "attributes": {},
      "resource": {
        "id": "M2DDT39A",
        "type": "merchant",
        "name": "Acme Corp",
        "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
        "created_at": "2023-01-20T15:16:17Z",
        "updated_at": "2023-01-20T15:16:17Z",
        "attributes": {}
      }
    }
  ],
  "total_count": 3
}

MembersPreview feature

Endpoints to manage account members. Members are users that have membership within merchant accounts.

The Member object

A member is user within specific resource identified by resource id, resource type, and associated roles.

Member

  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at  string  required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

    Example: "2023-01-20T15:16:17Z"
  • user  object

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email  string  required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

    • service_account_user  boolean  required

      True if the user is a service account.

    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • nickname  string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture  string

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
  • invite  object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email  string  required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • status  string  required

    The status of the membership.

  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
The Member object
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

List members

Lists merchant members.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

  • offset  integer
    0
  • limit  integer
    Example: 10
  • scroll  boolean
    Example: true
  • email  string
    Example: user
  • user.id  string
    Example: 245b2ead-85bf-45ff-856f-311a88a5d454
  • status  string
  • roles  []string
    Example: role_employeerole_accountant

Response 200

  • items  []object  required
     Show attributes
     Close
    Member
    • id  string  required

      ID of the member.

      Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • roles  []string  required

      User's roles.

       Show attributes
       Close
      Attributes
    • permissions  []string  required

      User's permissions.

       Show attributes
       Close
      Attributes
    • created_at  string  required

      The timestamp of when the member was created.

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

      The timestamp of when the member was last updated.

      Example: "2023-01-20T15:16:17Z"
    • user  object

      Information about the user associated with the membership.

       Show attributes
       Close
      Attributes
      • id  string  required

        Identifier for the End-User (also called Subject).

        Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
      • email  string  required

        End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

        Example: "example@sumup.com"
      • mfa_on_login_enabled  boolean  required

        True if the user has enabled MFA on login.

        Example: true
      • virtual_user  boolean  required

        True if the user is a virtual user (operator).

      • service_account_user  boolean  required

        True if the user is a service account.

      • disabled_at  string

        Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

      • nickname  string

        User's preferred name. Used for display purposes only.

        Example: "Test User"
      • picture  string

        URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

        Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
      • classic  object

        Classic identifiers of the user.

         Show attributes
         Close
        Attributes
        • user_id  integer  required
    • invite  object

      Pending invitation for membership.

       Show attributes
       Close
      Invite
      • email  string  required

        Email address of the invited user.

        Example: "boaty.mcboatface@sumup.com"
      • expires_at  string  required
        Example: "2023-01-20T15:16:17Z"
    • status  string  required

      The status of the membership.

    • metadata  object

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

       Show attributes
       Close
      Attributes
      Example: {}
    • attributes  object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • total_count  integer
    Example: 3
GET /v0.1/merchants/{merchant_code}/members 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.members.list("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.members.list("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Members.List(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.members().list(&"MC0X0ABC".to_string()).await;
List members response
{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "roles": [
        "role_admin",
        "role_owner"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-02-20T15:16:17Z",
      "user": {
        "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
        "email": "example@sumup.com",
        "mfa_on_login_enabled": true,
        "virtual_user": false,
        "service_account_user": false
      },
      "status": "accepted"
    }
  ],
  "total_count": 3
}
Members

Create a member

Create a merchant member.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

  • is_managed_user  boolean

    True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.

  • email  string  required

    Email address of the member to add.

  • password  string

    Password of the member to add. Only used if is_managed_user is true. In the case of service accounts, the password is not used and can not be defined by the caller.

  • nickname  string

    Nickname of the member to add. Only used if is_managed_user is true. Used for display purposes only.

    Example: "Test User"
  • roles  []string  required

    List of roles to assign to the new member. In the case of service accounts, the roles are predefined.

     Show attributes
     Close
    Attributes
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}

Member

  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at  string  required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

    Example: "2023-01-20T15:16:17Z"
  • user  object

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email  string  required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

    • service_account_user  boolean  required

      True if the user is a service account.

    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • nickname  string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture  string

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
  • invite  object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email  string  required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • status  string  required

    The status of the membership.

  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
POST /v0.1/merchants/{merchant_code}/members 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "email": "karl.berg@example.com",
    "roles": [
      "role_employee"
    ]
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.members.create("MC0X0ABC", {
  email: "karl.berg@example.com",
  roles: ["role_employee"],
});
from sumup import Sumup


client = SumUp()


res = sumup.members.create("MC0X0ABC", CreateMerchantMemberBody(
  email="karl.berg@example.com",
  roles=["role_employee"],
))
client := sumup.NewClient()


result, err := client.Members.Create(context.Background(), "MC0X0ABC", members.CreateMerchantMemberBody{
  Email: "karl.berg@example.com",
  Roles: ["role_employee"],
})
use sumup::Client;


let client = Client::default();


let result = client.members().create(&"MC0X0ABC".to_string(), sumup::CreateMerchantMemberBody {
  email: "karl.berg@example.com".to_string(),
  roles: vec!["role_employee"],
}).await;
Create a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Retrieve a member

Retrieve a merchant member.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • member_id  string  required
    Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Member

  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at  string  required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

    Example: "2023-01-20T15:16:17Z"
  • user  object

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email  string  required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

    • service_account_user  boolean  required

      True if the user is a service account.

    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • nickname  string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture  string

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
  • invite  object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email  string  required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • status  string  required

    The status of the membership.

  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
GET /v0.1/merchants/{merchant_code}/members/{member_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.members.get("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
from sumup import Sumup


client = SumUp()


res = sumup.members.get("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Members.Get(context.Background(), "MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.members().get(&"MC0X0ABC".to_string(), &"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string()).await;
Retrieve a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Update a member

Update the merchant member.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • member_id  string  required
    Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Body Parameters

  • roles  []string
     Show attributes
     Close
    Attributes
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • user  object

    Allows you to update user data of managed users.

     Show attributes
     Close
    Attributes
    • nickname  string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • password  string

      Password of the member to add. Only used if is_managed_user is true.

Member

  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at  string  required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

    Example: "2023-01-20T15:16:17Z"
  • user  object

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email  string  required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

    • service_account_user  boolean  required

      True if the user is a service account.

    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • nickname  string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture  string

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
  • invite  object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email  string  required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • status  string  required

    The status of the membership.

  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes  object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
PUT /v0.1/merchants/{merchant_code}/members/{member_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "Update member\'s role": {
      "roles": [
        "role_manager"
      ]
    },
    "Update managed user": {
      "user": {
        "nickname": "New Employee Name"
      }
    }
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.members.update("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", {
  Update member's role: {"roles":["role_manager"]},
  Update managed user: {"user":{"nickname":"New Employee Name"}},
});
from sumup import Sumup


client = SumUp()


res = sumup.members.update("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantMemberBody(
  Update member's role={"roles":["role_manager"]},
  Update managed user={"user":{"nickname":"New Employee Name"}},
))
client := sumup.NewClient()


result, err := client.Members.Update(context.Background(), "MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", members.UpdateMerchantMemberBody{
  UpdateMemberSRole: {"roles":["role_manager"]},
  UpdateManagedUser: {"user":{"nickname":"New Employee Name"}},
})
use sumup::Client;


let client = Client::default();


let result = client.members().update(&"MC0X0ABC".to_string(), &"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string(), sumup::UpdateMerchantMemberBody {
  update_member_s_role: {"roles":["role_manager"]},
  update_managed_user: {"user":{"nickname":"New Employee Name"}},
}).await;
Update a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Delete a member

Deletes a merchant member.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • member_id  string  required
    Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
DELETE /v0.1/merchants/{merchant_code}/members/{member_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.members.delete("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
from sumup import Sumup


client = SumUp()


res = sumup.members.delete("MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Members.Delete(context.Background(), "MC0X0ABC", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.members().delete(&"MC0X0ABC".to_string(), &"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string()).await;

RolesPreview feature

Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.

The Role object

A custom role that can be used to assign set of permissions to members.

Role

  • id  string  required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name  string  required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions  []string  required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined  boolean  required

    True if the role is provided by SumUp.

    Example: true
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
The Role object
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

List roles

List merchant's custom roles.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Response 200

  • items  []object  required
     Show attributes
     Close
    Role
    • id  string  required

      Unique identifier of the role.

      Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • name  string  required

      User-defined name of the role.

      Example: "Senior Shop Manager II"
    • description  string

      User-defined description of the role.

      Example: "Manges the shop and the employees."
    • permissions  []string  required

      List of permission granted by this role.

       Show attributes
       Close
      Attributes
    • is_predefined  boolean  required

      True if the role is provided by SumUp.

      Example: true
    • metadata  object

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

       Show attributes
       Close
      Attributes
      Example: {}
    • created_at  string  required

      The timestamp of when the role was created.

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

      The timestamp of when the role was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.roles.list("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.roles.list("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Roles.List(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.roles().list(&"MC0X0ABC".to_string()).await;
List roles response
{
  "items": [
    {
      "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "name": "Senior Shop Manager II",
      "description": "Manges the shop and the employees.",
      "permissions": [],
      "is_predefined": true,
      "metadata": {},
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Roles

Create a role

Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

  • name  string  required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."

Role

  • id  string  required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name  string  required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions  []string  required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined  boolean  required

    True if the role is provided by SumUp.

    Example: true
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager II",
    "permissions": [
      "catalog_access",
      "taxes_access",
      "members_access"
    ]
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.roles.create("MC0X0ABC", {
  name: "Senior Shop Manager II",
  permissions: ["catalog_access","taxes_access","members_access"],
});
from sumup import Sumup


client = SumUp()


res = sumup.roles.create("MC0X0ABC", CreateMerchantRoleBody(
  name="Senior Shop Manager II",
  permissions=["catalog_access","taxes_access","members_access"],
))
client := sumup.NewClient()


result, err := client.Roles.Create(context.Background(), "MC0X0ABC", roles.CreateMerchantRoleBody{
  Name: "Senior Shop Manager II",
  Permissions: ["catalog_access","taxes_access","members_access"],
})
use sumup::Client;


let client = Client::default();


let result = client.roles().create(&"MC0X0ABC".to_string(), sumup::CreateMerchantRoleBody {
  name: "Senior Shop Manager II".to_string(),
  permissions: vec!["catalog_access", "taxes_access", "members_access"],
}).await;
Create a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Retrieve a role

Retrieve a custom role by ID.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • role_id  string  required
    Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Role

  • id  string  required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name  string  required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions  []string  required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined  boolean  required

    True if the role is provided by SumUp.

    Example: true
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.roles.get("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
from sumup import Sumup


client = SumUp()


res = sumup.roles.get("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Roles.Get(context.Background(), "MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.roles().get(&"MC0X0ABC".to_string(), &"role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string()).await;
Retrieve a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Update a role

Update a custom role.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • role_id  string  required
    Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Body Parameters

  • name  string

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions  []string

    User's permissions.

     Show attributes
     Close
    Attributes
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."

Role

  • id  string  required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name  string  required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description  string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions  []string  required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined  boolean  required

    True if the role is provided by SumUp.

    Example: true
  • metadata  object

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager III",
    "permissions": [
      "catalog_edit",
      "taxes_access",
      "members_edit"
    ]
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.roles.update("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", {
  name: "Senior Shop Manager III",
  permissions: ["catalog_edit","taxes_access","members_edit"],
});
from sumup import Sumup


client = SumUp()


res = sumup.roles.update("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantRoleBody(
  name="Senior Shop Manager III",
  permissions=["catalog_edit","taxes_access","members_edit"],
))
client := sumup.NewClient()


result, err := client.Roles.Update(context.Background(), "MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", roles.UpdateMerchantRoleBody{
  Name: "Senior Shop Manager III",
  Permissions: ["catalog_edit","taxes_access","members_edit"],
})
use sumup::Client;


let client = Client::default();


let result = client.roles().update(&"MC0X0ABC".to_string(), &"role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string(), sumup::UpdateMerchantRoleBody {
  name: "Senior Shop Manager III".to_string(),
  permissions: vec!["catalog_edit", "taxes_access", "members_edit"],
}).await;
Update a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Delete a role

Delete a custom role.

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • role_id  string  required
    Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
DELETE /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.roles.delete("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
from sumup import Sumup


client = SumUp()


res = sumup.roles.delete("MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Roles.Delete(context.Background(), "MC0X0ABC", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.roles().delete(&"MC0X0ABC".to_string(), &"role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP".to_string()).await;

Merchants

Merchant account represents a single business entity at SumUp.

The Merchant object

Merchant

  • merchant_code  string

    Short unique identifier for the merchant.

    Example: "MK01A8C2"
  • organization_id  string

    ID of the organization the merchant belongs to (if any).

    Example: "G0UZPVAX"
  • business_type  string

    The business type.

    • sole_trader: The business is run by an self-employed individual.
    • company: The business is run as a company with one or more shareholders
    • partnership: The business is run as a company with two or more shareholders that can be also other legal entities
    • non_profit: The business is run as a nonprofit organization that operates for public or social benefit
    • government_entity: The business is state owned and operated
  • company  object

    Information about the company or business. This is legal information that is used for verification.

     Show attributes
     Close
    Attributes
    • name  string

      The company's legal name.

      Example: "Gin & Doughnuts Bar GmbH"
    • merchant_category_code  string

      The merchant category code for the account as specified by ISO18245. MCCs are used to classify businesses based on the goods or services they provide.

      Example: "1532"
    • legal_type  string

      The unique legal type reference as defined in the country SDK. We do not rely on IDs as used by other services. Consumers of this API are expected to use the country SDK to map to any other IDs, translation keys, or descriptions.

    • address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • trading_address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers  []object

      A list of country-specific company identifiers.

    • phone_number  string

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • website  string

      HTTP(S) URL of the company's website.

    • attributes  object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • country  string

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • business_profile  object

    Business information about the merchant. This information will be visible to the merchant's customers.

     Show attributes
     Close
    Attributes
    • name  string

      The customer-facing business name.

      Example: "Gin & Dougnuts"
    • dynamic_descriptor  string

      The descriptor is the text that your customer sees on their bank account statement. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).

    • website  string

      The business's publicly available website.

      Example: "https://gindoughnuts.com"
    • email  string

      A publicly available email address.

      Example: "contact@gindoughnuts.com"
    • phone_number  string

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • branding  object

      Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.

       Show attributes
       Close
      Attributes
      • icon  string

        An icon for the merchant. Must be square.

      • logo  string

        A logo for the merchant that will be used in place of the icon and without the merchant's name next to it if there's sufficient space.

      • hero  string

        Data-URL encoded hero image for the merchant business.

      • primary_color  string

        A hex color value representing the primary branding color of this merchant (your brand color).

      • primary_color_fg  string

        A hex color value representing the color of the text displayed on branding color of this merchant.

      • secondary_color  string

        A hex color value representing the secondary branding color of this merchant (accent color used for buttons).

      • secondary_color_fg  string

        A hex color value representing the color of the text displayed on secondary branding color of this merchant.

      • background_color  string

        A hex color value representing the preferred background color of this merchant.

  • avatar  string

    A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.

  • alias  string

    A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see merchant.business_profile.

  • default_currency  string

    Three-letter ISO currency code representing the default currency for the account.

    Example: "EUR"
  • default_locale  string

    Merchant's default locale, represented as a BCP47 RFC5646 language tag. This is typically an ISO 639-1 Alpha-2 ISO639‑1 language code in lowercase and an ISO 3166-1 Alpha-2 ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or fr-CA. In multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language.

    Example: "de-DE"
  • sandbox  boolean

    True if the merchant is a sandbox for testing.

  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • classic  object
     Show attributes
     Close
    Attributes
    • id  integer  required

      Classic (serial) merchant ID.

      Example: 1234
  • version  string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status  string

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

  • created_at  string

    The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.

  • updated_at  string

    The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

The Merchant object
{
  "merchant_code": "MK01A8C2",
  "organization_id": "G0UZPVAX",
  "business_type": null,
  "company": {
    "name": "Gin & Doughnuts Bar GmbH",
    "merchant_category_code": "1532",
    "legal_type": "de.freiberufler",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "trading_address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "identifiers": [
      {
        "ref": "de.gmbh",
        "value": "HRB 123456"
      }
    ],
    "phone_number": "+420123456789",
    "website": "https://www.sumup.com",
    "attributes": {}
  },
  "country": "BR",
  "business_profile": {
    "name": "Gin & Dougnuts",
    "dynamic_descriptor": null,
    "website": "https://gindoughnuts.com",
    "email": "contact@gindoughnuts.com",
    "phone_number": "+420123456789",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "branding": {
      "icon": null,
      "logo": null,
      "hero": null,
      "primary_color": "#FF4B3A",
      "primary_color_fg": "#FF4B3A",
      "secondary_color": "#FF4B3A",
      "secondary_color_fg": "#FF4B3A",
      "background_color": "#FF4B3A"
    }
  },
  "avatar": null,
  "alias": null,
  "default_currency": "EUR",
  "default_locale": "de-DE",
  "sandbox": null,
  "meta": {},
  "classic": {
    "id": 1234
  },
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null,
  "created_at": "2021-08-31T12:00:00Z",
  "updated_at": "2021-08-31T12:00:00Z"
}
Merchants

Retrieve a Merchant

Retrieve a merchant.

Required scopes: user.profile user.profile_readonly merchant.read

Path Parameters

  • merchant_code  string  required
    Example: MK10CL2A

Query Parameters

  • version  string

Merchant

  • merchant_code  string

    Short unique identifier for the merchant.

    Example: "MK01A8C2"
  • organization_id  string

    ID of the organization the merchant belongs to (if any).

    Example: "G0UZPVAX"
  • business_type  string

    The business type.

    • sole_trader: The business is run by an self-employed individual.
    • company: The business is run as a company with one or more shareholders
    • partnership: The business is run as a company with two or more shareholders that can be also other legal entities
    • non_profit: The business is run as a nonprofit organization that operates for public or social benefit
    • government_entity: The business is state owned and operated
  • company  object

    Information about the company or business. This is legal information that is used for verification.

     Show attributes
     Close
    Attributes
    • name  string

      The company's legal name.

      Example: "Gin & Doughnuts Bar GmbH"
    • merchant_category_code  string

      The merchant category code for the account as specified by ISO18245. MCCs are used to classify businesses based on the goods or services they provide.

      Example: "1532"
    • legal_type  string

      The unique legal type reference as defined in the country SDK. We do not rely on IDs as used by other services. Consumers of this API are expected to use the country SDK to map to any other IDs, translation keys, or descriptions.

    • address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • trading_address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers  []object

      A list of country-specific company identifiers.

    • phone_number  string

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • website  string

      HTTP(S) URL of the company's website.

    • attributes  object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • country  string

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • business_profile  object

    Business information about the merchant. This information will be visible to the merchant's customers.

     Show attributes
     Close
    Attributes
    • name  string

      The customer-facing business name.

      Example: "Gin & Dougnuts"
    • dynamic_descriptor  string

      The descriptor is the text that your customer sees on their bank account statement. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).

    • website  string

      The business's publicly available website.

      Example: "https://gindoughnuts.com"
    • email  string

      A publicly available email address.

      Example: "contact@gindoughnuts.com"
    • phone_number  string

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • branding  object

      Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.

       Show attributes
       Close
      Attributes
      • icon  string

        An icon for the merchant. Must be square.

      • logo  string

        A logo for the merchant that will be used in place of the icon and without the merchant's name next to it if there's sufficient space.

      • hero  string

        Data-URL encoded hero image for the merchant business.

      • primary_color  string

        A hex color value representing the primary branding color of this merchant (your brand color).

      • primary_color_fg  string

        A hex color value representing the color of the text displayed on branding color of this merchant.

      • secondary_color  string

        A hex color value representing the secondary branding color of this merchant (accent color used for buttons).

      • secondary_color_fg  string

        A hex color value representing the color of the text displayed on secondary branding color of this merchant.

      • background_color  string

        A hex color value representing the preferred background color of this merchant.

  • avatar  string

    A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.

  • alias  string

    A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see merchant.business_profile.

  • default_currency  string

    Three-letter ISO currency code representing the default currency for the account.

    Example: "EUR"
  • default_locale  string

    Merchant's default locale, represented as a BCP47 RFC5646 language tag. This is typically an ISO 639-1 Alpha-2 ISO639‑1 language code in lowercase and an ISO 3166-1 Alpha-2 ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or fr-CA. In multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language.

    Example: "de-DE"
  • sandbox  boolean

    True if the merchant is a sandbox for testing.

  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • classic  object
     Show attributes
     Close
    Attributes
    • id  integer  required

      Classic (serial) merchant ID.

      Example: 1234
  • version  string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status  string

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

  • created_at  string

    The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.

  • updated_at  string

    The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

GET /v1/merchants/{merchant_code} 
curl https://api.sumup.com/v1/merchants/{merchant_code} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchants.get("MK10CL2A");
from sumup import Sumup


client = SumUp()


res = sumup.merchants.get("MK10CL2A")
client := sumup.NewClient()


result, err := client.Merchants.Get(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.merchants().get(&"MK10CL2A".to_string()).await;
Retrieve a Merchant response
{
  "merchant_code": "MK01A8C2",
  "organization_id": "G0UZPVAX",
  "business_type": null,
  "company": {
    "name": "Gin & Doughnuts Bar GmbH",
    "merchant_category_code": "1532",
    "legal_type": "de.freiberufler",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "trading_address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "identifiers": [
      {
        "ref": "de.gmbh",
        "value": "HRB 123456"
      }
    ],
    "phone_number": "+420123456789",
    "website": "https://www.sumup.com",
    "attributes": {}
  },
  "country": "BR",
  "business_profile": {
    "name": "Gin & Dougnuts",
    "dynamic_descriptor": null,
    "website": "https://gindoughnuts.com",
    "email": "contact@gindoughnuts.com",
    "phone_number": "+420123456789",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "branding": {
      "icon": null,
      "logo": null,
      "hero": null,
      "primary_color": "#FF4B3A",
      "primary_color_fg": "#FF4B3A",
      "secondary_color": "#FF4B3A",
      "secondary_color_fg": "#FF4B3A",
      "background_color": "#FF4B3A"
    }
  },
  "avatar": null,
  "alias": null,
  "default_currency": "EUR",
  "default_locale": "de-DE",
  "sandbox": null,
  "meta": {},
  "classic": {
    "id": 1234
  },
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null,
  "created_at": "2021-08-31T12:00:00Z",
  "updated_at": "2021-08-31T12:00:00Z"
}
Merchants

List Persons

Returns a list of persons related to the merchant.

Required scopes: user.profile user.profile_readonly merchant.read

Path Parameters

  • merchant_code  string  required
    Example: MK10CL2A

Query Parameters

  • version  string

Response 200

  • items  []object  required
     Show attributes
     Close
    Attributes
    • id  string

      The unique identifier for the person. This is a typeid.

    • user_id  string

      A corresponding identity user ID for the person, if they have a user account.

    • birthdate  string

      The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.

      Example: "1980-01-12"
    • given_name  string

      The first name(s) of the individual.

      Example: "James Herrald"
    • family_name  string

      The last name(s) of the individual.

      Example: "Bond"
    • middle_name  string

      Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

      Example: "Maria Sophie"
    • phone_number  string

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • relationships  []string

      A list of roles the person has in the merchant or towards SumUp. A merchant must have at least one person with the relationship representative.

       Show attributes
       Close
      Attributes
    • ownership  object
       Show attributes
       Close
      Attributes
      • share  integer  required

        The percent of ownership shares held by the person expressed in percent mille (1/100000). Only persons with the relationship owner can have ownership.

        Example: 50000
    • address  object

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address  []string
         Show attributes
         Close
        Attributes
      • post_code  string

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country  string  required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city  string

        The city of the address.

        Example: "Berlin"
      • province  string

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region  string

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county  string

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community  string

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town  string

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state  string

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood  string

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune  string

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department  string

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality  string

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district  string

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code  string

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode  string

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers  []object

      A list of country-specific personal identifiers.

       Show attributes
       Close
      Attributes
      • ref  string  required

        The unique reference for the personal identifier type.

        Example: "br.cpf"
      • value  string  required

        The company identifier value.

        Example: "847.060.136-90"
    • citizenship  string

      An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

      Example: "BR"
    • version  string

      The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

    • change_status  string

      Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

GET /v1/merchants/{merchant_code}/persons 
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchants.listPersons("MK10CL2A");
from sumup import Sumup


client = SumUp()


res = sumup.merchants.list_persons("MK10CL2A")
client := sumup.NewClient()


result, err := client.Merchants.ListPersons(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.merchants().list_persons(&"MK10CL2A".to_string()).await;
List Persons response
{
  "items": [
    {
      "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
      "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
      "birthdate": "1980-01-12",
      "given_name": "James Herrald",
      "family_name": "Bond",
      "middle_name": "Maria Sophie",
      "phone_number": "+420123456789",
      "relationships": [
        "representative"
      ],
      "ownership": {
        "share": 50000
      },
      "address": {
        "street_address": [
          "Paul-Linke-Ufer 39-40",
          "2. Hinterhof"
        ],
        "post_code": "10999",
        "city": "Berlin",
        "country": "DE"
      },
      "identifiers": [
        {
          "ref": "br.cpf",
          "value": "847.060.136-90"
        }
      ],
      "citizenship": "BR",
      "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
      "change_status": null
    }
  ]
}
Merchants

Retrieve a Person

Returns a single person related to the merchant.

Required scopes: user.profile user.profile_readonly merchant.read

Path Parameters

  • merchant_code  string  required
    Example: MK10CL2A
  • person_id  string  required
    Example: pers_5AKFHN2KSK8D3TS79DJE3P3A2Z

Query Parameters

  • version  string

Response 200

  • id  string

    The unique identifier for the person. This is a typeid.

  • user_id  string

    A corresponding identity user ID for the person, if they have a user account.

  • birthdate  string

    The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.

    Example: "1980-01-12"
  • given_name  string

    The first name(s) of the individual.

    Example: "James Herrald"
  • family_name  string

    The last name(s) of the individual.

    Example: "Bond"
  • middle_name  string

    Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

    Example: "Maria Sophie"
  • phone_number  string

    A publicly available phone number in E.164 format.

    Example: "+420123456789"
  • relationships  []string

    A list of roles the person has in the merchant or towards SumUp. A merchant must have at least one person with the relationship representative.

     Show attributes
     Close
    Attributes
  • ownership  object
     Show attributes
     Close
    Attributes
    • share  integer  required

      The percent of ownership shares held by the person expressed in percent mille (1/100000). Only persons with the relationship owner can have ownership.

      Example: 50000
  • address  object

    An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

     Show attributes
     Close
    Attributes
    • street_address  []string
       Show attributes
       Close
      Attributes
    • post_code  string

      The postal code (aka. zip code) of the address.

      Example: "10999"
    • country  string  required

      An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

      Example: "BR"
    • city  string

      The city of the address.

      Example: "Berlin"
    • province  string

      The province where the address is located. This may not be relevant in some countries.

      Example: "Berlin"
    • region  string

      The region where the address is located. This may not be relevant in some countries.

      Example: "Baden Wuerttemberg"
    • county  string

      A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

      Example: "Dublin County"
    • autonomous_community  string

      In Spain, an autonomous community is the first sub-national level of political and administrative division.

      Example: "Catalonia"
    • post_town  string

      A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

      Example: "London"
    • state  string

      Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

      Example: "California"
    • neighborhood  string

      Locality level of the address. Used in countries such as Brazil or Chile.

      Example: "Copacabana"
    • commune  string

      In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

      Example: "Providencia"
    • department  string

      A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

      Example: "Antioquia"
    • municipality  string

      A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

      Example: "Medellín"
    • district  string

      A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

      Example: "Lisbon District"
    • zip_code  string

      A US system of postal codes used by the United States Postal Service (USPS).

      Example: "94103"
    • eircode  string

      A postal address in Ireland.

      Example: "D02 X285"
    Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
  • identifiers  []object

    A list of country-specific personal identifiers.

     Show attributes
     Close
    Attributes
    • ref  string  required

      The unique reference for the personal identifier type.

      Example: "br.cpf"
    • value  string  required

      The company identifier value.

      Example: "847.060.136-90"
  • citizenship  string

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • version  string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status  string

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

GET /v1/merchants/{merchant_code}/persons/{person_id} 
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons/{person_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.merchants.getPerson("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z");
from sumup import Sumup


client = SumUp()


res = sumup.merchants.get_person("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")
client := sumup.NewClient()


result, err := client.Merchants.GetPerson(context.Background(), "MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")
use sumup::Client;


let client = Client::default();


let result = client.merchants().get_person(&"MK10CL2A".to_string(), &"pers_5AKFHN2KSK8D3TS79DJE3P3A2Z".to_string()).await;
Retrieve a Person response
{
  "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
  "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
  "birthdate": "1980-01-12",
  "given_name": "James Herrald",
  "family_name": "Bond",
  "middle_name": "Maria Sophie",
  "phone_number": "+420123456789",
  "relationships": [
    "representative"
  ],
  "ownership": {
    "share": 50000
  },
  "address": {
    "street_address": [
      "Paul-Linke-Ufer 39-40",
      "2. Hinterhof"
    ],
    "post_code": "10999",
    "city": "Berlin",
    "country": "DE"
  },
  "identifiers": [
    {
      "ref": "br.cpf",
      "value": "847.060.136-90"
    }
  ],
  "citizenship": "BR",
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null
}

ReadersPreview feature

A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.

The Reader object

A physical card reader device that can accept in-person payments.

Reader

  • id  string  required

    Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name  string  required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status  string  required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device  object  required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier  string  required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model  string  required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at  string  required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
The Reader object
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "meta": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

List Readers

List all readers of the merchant.

Required scopes: readers.read

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Response 200

  • items  []object  required
     Show attributes
     Close
    Reader
    • id  string  required

      Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

      Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
    • name  string  required

      Custom human-readable, user-defined name for easier identification of the reader.

      Example: "Frontdesk"
    • status  string  required

      The status of the reader object gives information about the current state of the reader.

      Possible values:

      • unknown - The reader status is unknown.
      • processing - The reader is created and waits for the physical device to confirm the pairing.
      • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
      • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
      Example: "paired"
    • device  object  required

      Information about the underlying physical device.

       Show attributes
       Close
      Attributes
      • identifier  string  required

        A unique identifier of the physical device (e.g. serial number).

        Example: "U1DT3NA00-CN"
      • model  string  required
        Options:  solo virtual-solo

        Identifier of the model of the device.

        Example: "solo"
    • meta  object

      A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

      Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

       Show attributes
       Close
      Attributes
      Example: {}
    • created_at  string  required

      The timestamp of when the reader was created.

      Example: "2023-01-18T15:16:17Z"
    • updated_at  string  required

      The timestamp of when the reader was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.list("MC0X0ABC");
from sumup import Sumup


client = SumUp()


res = sumup.readers.list("MC0X0ABC")
client := sumup.NewClient()


result, err := client.Readers.List(context.Background(), "MC0X0ABC")
use sumup::Client;


let client = Client::default();


let result = client.readers().list(&"MC0X0ABC".to_string()).await;
List Readers response
{
  "items": [
    {
      "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
      "name": "Frontdesk",
      "status": "paired",
      "device": {
        "identifier": "U1DT3NA00-CN",
        "model": "solo"
      },
      "meta": {},
      "created_at": "2023-01-18T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Readers

Create a Reader

Create a new Reader for the merchant account.

Required scopes: readers.write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

  • pairing_code  string  required

    The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing.

    Example: "4WLFDSBF"
  • name  string  required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}

Reader

  • id  string  required

    Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name  string  required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status  string  required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device  object  required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier  string  required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model  string  required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at  string  required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "pairing_code": "4WLFDSBF",
    "name": "Frontdesk"
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.create("MC0X0ABC", {
  pairing_code: "4WLFDSBF",
  name: "Frontdesk",
});
from sumup import Sumup


client = SumUp()


res = sumup.readers.create("MC0X0ABC", CreateReaderBody(
  pairing_code="4WLFDSBF",
  name="Frontdesk",
))
client := sumup.NewClient()


result, err := client.Readers.Create(context.Background(), "MC0X0ABC", readers.CreateReaderBody{
  PairingCode: "4WLFDSBF",
  Name: "Frontdesk",
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create(&"MC0X0ABC".to_string(), sumup::CreateReaderBody {
  pairing_code: "4WLFDSBF".to_string(),
  name: "Frontdesk".to_string(),
}).await;
Response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "processing",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "created_at": "2023-05-09T14:50:20.214Z",
  "updated_at": "2023-05-09T14:52:58.714Z"
}
Readers

Retrieve a Reader

Retrieve a Reader.

Required scopes: readers.read

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • id  string  required
    Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Reader

  • id  string  required

    Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name  string  required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status  string  required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device  object  required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier  string  required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model  string  required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at  string  required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.get("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
from sumup import Sumup


client = SumUp()


res = sumup.readers.get("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
client := sumup.NewClient()


result, err := client.Readers.Get(context.Background(), "MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().get(&"MC0X0ABC".to_string(), &"rdr_3MSAFM23CK82VSTT4BN6RWSQ65".to_string()).await;
Retrieve a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "meta": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Update a Reader

Update a Reader.

Required scopes: readers.write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • id  string  required
    Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Body Parameters

  • name  string

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}

Reader

  • id  string  required

    Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name  string  required

    Custom human-readable, user-defined name for easier identification of the reader.

    Example: "Frontdesk"
  • status  string  required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device  object  required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier  string  required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model  string  required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • meta  object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required

    The timestamp of when the reader was created.

    Example: "2023-01-18T15:16:17Z"
  • updated_at  string  required

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.update("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", {


});
from sumup import Sumup


client = SumUp()


res = sumup.readers.update("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", UpdateReaderBody(


))
client := sumup.NewClient()


result, err := client.Readers.Update(context.Background(), "MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", readers.UpdateReaderBody{


})
use sumup::Client;


let client = Client::default();


let result = client.readers().update(&"MC0X0ABC".to_string(), &"rdr_3MSAFM23CK82VSTT4BN6RWSQ65".to_string(), sumup::UpdateReaderBody {


}).await;
Update a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "meta": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Delete a reader

Delete a reader.

Required scopes: readers.write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • id  string  required
    Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65
DELETE /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.deleteReader("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
from sumup import Sumup


client = SumUp()


res = sumup.readers.delete_reader("MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
client := sumup.NewClient()


result, err := client.Readers.DeleteReader(context.Background(), "MC0X0ABC", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().delete_reader(&"MC0X0ABC".to_string(), &"rdr_3MSAFM23CK82VSTT4BN6RWSQ65".to_string()).await;
Readers

Create a Reader Checkout

Creates a Checkout for a Reader.

This process is asynchronous and the actual transaction may take some time to be stared on the device.

There are some caveats when using this endpoint:

  • The target device must be online, otherwise checkout won't be accepted
  • After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.

Note: If the target device is a Solo, it must be in version 3.3.24.3 or higher.

Required scopes: readers.write

Path Parameters

  • merchant_code  string  required
  • reader_id  string  required

CreateReaderCheckoutRequest

  • affiliate  object

    Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction.

     Show attributes
     Close
    Affiliate
    • app_id  string  required

      Application ID of the affiliate. It is a unique identifier for the application and should be set by the integrator in the Affiliate Keys page.

      Example: "com.example.app"
    • foreign_transaction_id  string  required

      Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It can be used later to fetch the transaction details via the Transactions API.

      Example: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f"
    • key  string  required

      Key of the affiliate. It is a unique identifier for the key and should be generated by the integrator in the Affiliate Keys page.

      Example: "123e4567-e89b-12d3-a456-426614174000"
    • tags  object

      Additional metadata for the transaction. It is key-value object that can be associated with the transaction.

       Show attributes
       Close
      Attributes
      Example: {"custom_key_1":"custom_value_1","custom_key_2":"custom_value_2"}
  • card_type  string
    Options:  credit debit

    The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil).

    Example: "credit"
  • description  string

    Description of the checkout to be shown in the Merchant Sales

  • installments  integer

    Number of installments for the transaction. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12.

    Example: 1
  • return_url  string

    Webhook URL to which the payment result will be sent. It must be a HTTPS url.

    Example: "https://www.example.com"
  • tip_rates  []number

    List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order.

     Show attributes
     Close
    Attributes
  • tip_timeout  integer

    Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds.

    It can only be set if tip_rates is provided.

    Note: If the target device is a Solo, it must be in version 3.3.38.0 or higher.

    Example: 30
  • total_amount  object  required

    Amount structure.

    The amount is represented as an integer value altogether with the currency and the minor unit.

    For example, EUR 1.00 is represented as value 100 with minor unit of 2.

     Show attributes
     Close
    Money
    • currency  string  required

      Currency ISO 4217 code

      Example: "EUR"
    • minor_unit  integer  required

      The minor units of the currency. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.

      Example: 2
    • value  integer  required

      Integer value of the amount.

      Example: 1000
    Example: {"currency":"EUR","minor_unit":2,"value":1000}

CreateReaderCheckoutResponse

  • data  object  required
     Show attributes
     Close
    Attributes
    • client_transaction_id  string  required

      The client transaction ID is a unique identifier for the transaction that is generated for the client.

      It can be used later to fetch the transaction details via the Transactions API.

      Example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "total_amount": {
      "currency": "EUR",
      "minor_unit": 2,
      "value": 5033
    }
  }'
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.createCheckout("merchant_code", "reader_id", {
  total_amount: {
    currency: "EUR",
    minor_unit: 2,
    value: 5033,
  },
});
from sumup import Sumup


client = SumUp()


res = sumup.readers.create_checkout("merchant_code", "reader_id", CreateReaderCheckoutBody(
  total_amount=Money(
    currency="EUR",
    minor_unit=2,
    value=5033,
  ),
))
client := sumup.NewClient()


result, err := client.Readers.CreateCheckout(context.Background(), "merchant_code", "reader_id", readers.CreateReaderCheckoutBody{
  TotalAmount: readers.Money{
    Currency: "EUR",
    MinorUnit: 2,
    Value: 5033,
  },
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create_checkout(&"merchant_code".to_string(), &"reader_id".to_string(), sumup::CreateReaderCheckoutBody {
  total_amount: sumup::Money {
    currency: "EUR".to_string(),
    minor_unit: 2,
    value: 5033,
  },
}).await;
Create a Reader Checkout response
{
  "data": {
    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
Readers

Terminate a Reader Checkout

Terminate a Reader Checkout stops the current transaction on the target device.

This process is asynchronous and the actual termination may take some time to be performed on the device.

There are some caveats when using this endpoint:

  • The target device must be online, otherwise terminate won't be accepted
  • The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.
  • There is no confirmation of the termination.

If a transaction is successfully terminated and return_url was provided on Checkout, the transaction status will be sent as failed to the provided URL.

Note: If the target device is a Solo, it must be in version 3.3.28.0 or higher.

Required scopes: readers.write

Path Parameters

  • merchant_code  string  required
  • reader_id  string  required
POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp();


const res = await sumup.readers.terminateCheckout("merchant_code", "reader_id");
from sumup import Sumup


client = SumUp()


res = sumup.readers.terminate_checkout("merchant_code", "reader_id")
client := sumup.NewClient()


result, err := client.Readers.TerminateCheckout(context.Background(), "merchant_code", "reader_id")
use sumup::Client;


let client = Client::default();


let result = client.readers().terminate_checkout(&"merchant_code".to_string(), &"reader_id".to_string()).await;