SumUp REST API
SumUp’s REST API operates with application/json
HTTP requests and response. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes. For testing our APIs make sure you have a SumUp Profile (you can create one here). To activate your SumUp Profile follow these steps.
Once you have an active SumUp Profile, go to developer.sumup.com and click on “Create” On the top right side, click on “Profile” followed by “Test profiles” Select your business country Click “Create” Copy and store safely the user name (format: 32 characters@developers.sumup.com) and randomly generated unique password.
Note: You will not be able to access your password afterwards make sure to store it safely before dismissing the message
Note: SumUp merchants are able to create up to 20 test profiles
When you receive your test profile you can create your client credentials and process different requests with real payment instruments, without charging them. Legal note: We reserve the right to change, modify, or remove the contents of this Website and SumUp APIs at any time without notice.
https://api.sumup.com
Checkouts
Accept payments from your end users by adding the Checkouts model to your platform. SumUp supports standard and single payment 3DS checkout flows.
The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a checkout and then processing the checkout.
The Checkout object
Details of the payment checkout.
Attributes
- amount number
Amount of the payment.
Example:10.1
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
Example:"831ff8d4cd5958ab5670"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
Example:"4e425463-3e1b-431d-83fa-1e51c2925e99"
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- merchant_code string
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made.
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
{
"amount": 10.1,
"checkout_reference": null,
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": null,
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"merchant_code": null,
"pay_to_email": null,
"return_url": null,
"status": null,
"transactions": [
{
"amount": 10.1,
"currency": "EUR",
"id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
"installments_count": null,
"payment_type": null,
"status": null,
"timestamp": "2020-02-29T10:56:56.876Z",
"transaction_code": "TEENSK4W2K",
"auth_code": "053201",
"entry_mode": null,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"tip_amount": 3,
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00"
}
List checkouts
Lists created checkout resources according to the applied checkout_reference
.
payments
Query Parameters
- checkout_reference string
Response 200
- amount number
Amount of the payment.
Example:10.1
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
Example:"831ff8d4cd5958ab5670"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
Example:"4e425463-3e1b-431d-83fa-1e51c2925e99"
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- merchant_code string
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made.
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
- merchant_name string
Name of the merchant
Example:"Sample Merchant"
- payment_instrument object
Object containing token information for the specified payment instrument
CloseAttributes- token string
Token value
Example:"e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
-
- redirect_url string
Refers to a url where the end user is redirected once the payment processing completes.
Example:"https://mysite.com/completed_purchase"
- transaction_code string
Transaction code of the successful transaction with which the payment for the checkout is completed.
Example:"TEENSK4W2K"
- transaction_id string
Transaction ID of the successful transaction with which the payment for the checkout is completed.
Example:"410fc44a-5956-44e1-b5cc-19c6f8d727a4"
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/checkouts
[
{
"amount": 10.1,
"checkout_reference": null,
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": null,
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"merchant_code": null,
"pay_to_email": null,
"return_url": null,
"status": null,
"transactions": [
{
"amount": 10.1,
"currency": "EUR",
"id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
"installments_count": null,
"payment_type": null,
"status": null,
"timestamp": "2020-02-29T10:56:56.876Z",
"transaction_code": "TEENSK4W2K",
"auth_code": "053201",
"entry_mode": null,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"tip_amount": 3,
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00",
"merchant_name": "Sample Merchant",
"payment_instrument": {
"token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
},
"redirect_url": "https://mysite.com/completed_purchase",
"transaction_code": "TEENSK4W2K",
"transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
}
]
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.
payments
Body Parameters
- amount number required
Amount of the payment.
- checkout_reference string required
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string required
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
- merchant_code string required
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use
merchant_code
instead ofpay_to_email
. - payment_type string
Alternative payment method name
Example:"boleto"
- personal_details object
Object containing personal details about the payer, typical for Boleto checkouts
CloseAttributes- address object
Payer's address information
CloseAttributes- city string
Payer's city
Example:"Rio de Janeiro"
- country string
Payer's country
Example:"BR"
- line_1 string
Field for address details
- postal_code string
Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit (more information about the format available here). Both options are accepted as correct.
Example:"20000-000"
- state stringOptions:
AC
AL
AP
AM
BA
CE
DF
ES
GO
MA
MT
MS
MG
PA
PB
PR
PE
PI
RJ
RN
RS
RO
RR
SC
SP
SE
TO
Payer's state code
Example:"RJ"
-
- email string
Payer's email address
Example:"test@example.com"
- first_name string
Payer's first name
Example:"John"
- last_name string
Payer's last name
Example:"Doe"
- tax_id string
Payer's tax identification number (CPF)
Example:"423.378.593-47"
-
- purpose stringOptions:
CHECKOUT
SETUP_RECURRING_PAYMENT
Purpose of the checkout.
- 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"
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
Response 201
- amount number
Amount of the payment.
Example:10.1
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
Example:"831ff8d4cd5958ab5670"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
Example:"4e425463-3e1b-431d-83fa-1e51c2925e99"
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- merchant_code string
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made.
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
Response 400
- error_code string
Platform code for the error.
- message string
Short description of the error.
- param string
Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example,
card.name
refers to thename
parameter embedded in thecard
object.
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 409
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/checkouts
{
"amount": 10.1,
"checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": "My Checkout",
"id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"merchant_code": "MCNPLE22",
"merchant_country": "DE",
"pay_to_email": "user@example.com",
"return_url": "http://example.com",
"status": "PENDING",
"transactions": [
{
"amount": 10.1,
"auth_code": "012345",
"currency": "EUR",
"entry_mode": "CUSTOMER_ENTRY",
"id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"installments_count": 1,
"internal_id": 0,
"merchant_code": "MH4H92C7",
"payment_type": "ECOM",
"status": "SUCCESSFUL",
"timestamp": "2020-02-29T10:56:56.876Z",
"tip_amount": 3,
"transaction_code": "TEENSK4W2K",
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00"
}
{
"amount": 10.1,
"checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": "My Checkout",
"id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
"pay_to_email": "user@example.com",
"redirect_url": "https://mysite.com/completed_purchase",
"return_url": "http://example.com",
"status": "PENDING",
"transactions": [
{
"amount": 10.1,
"auth_code": "012345",
"currency": "EUR",
"entry_mode": "CUSTOMER_ENTRY",
"id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"installments_count": 1,
"internal_id": 0,
"merchant_code": "MH4H92C7",
"payment_type": "ECOM",
"status": "SUCCESSFUL",
"timestamp": "2020-02-29T10:56:56.876Z",
"tip_amount": 3,
"transaction_code": "TEENSK4W2K",
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00"
}
{
"amount": 10.1,
"checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
"currency": "EUR",
"date": "2021-06-29T11:08:36.000+00:00",
"description": "My Checkout",
"id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
"merchant_code": "MCNPLE22",
"merchant_country": "DE",
"merchant_name": "My company",
"pay_to_email": "user@example.com",
"purpose": "CHECKOUT",
"redirect_url": "https://sumup.com",
"return_url": "http://example.com",
"status": "PENDING",
"transactions": [
{
"amount": 10.1,
"auth_code": "012345",
"currency": "EUR",
"entry_mode": "CUSTOMER_ENTRY",
"id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"installments_count": 1,
"internal_id": 0,
"merchant_code": "MH4H92C7",
"payment_type": "ECOM",
"status": "SUCCESSFUL",
"timestamp": "2020-02-29T10:56:56.876Z",
"tip_amount": 3,
"transaction_code": "TEENSK4W2K",
"vat_amount": 6
}
]
}
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.
payments
Path Parameters
- id string required
Response 200
- amount number
Amount of the payment.
Example:10.1
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
Example:"831ff8d4cd5958ab5670"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
Example:"4e425463-3e1b-431d-83fa-1e51c2925e99"
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- merchant_code string
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made.
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
- merchant_name string
Name of the merchant
Example:"Sample Merchant"
- payment_instrument object
Object containing token information for the specified payment instrument
CloseAttributes- token string
Token value
Example:"e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
-
- redirect_url string
Refers to a url where the end user is redirected once the payment processing completes.
Example:"https://mysite.com/completed_purchase"
- transaction_code string
Transaction code of the successful transaction with which the payment for the checkout is completed.
Example:"TEENSK4W2K"
- transaction_id string
Transaction ID of the successful transaction with which the payment for the checkout is completed.
Example:"410fc44a-5956-44e1-b5cc-19c6f8d727a4"
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/checkouts/{id}
{
"amount": 10.1,
"checkout_reference": null,
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": null,
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"merchant_code": null,
"pay_to_email": null,
"return_url": null,
"status": null,
"transactions": [
{
"amount": 10.1,
"currency": "EUR",
"id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
"installments_count": null,
"payment_type": null,
"status": null,
"timestamp": "2020-02-29T10:56:56.876Z",
"transaction_code": "TEENSK4W2K",
"auth_code": "053201",
"entry_mode": null,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"tip_amount": 3,
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00",
"merchant_name": "Sample Merchant",
"payment_instrument": {
"token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
},
"redirect_url": "https://mysite.com/completed_purchase",
"transaction_code": "TEENSK4W2K",
"transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
}
Process a checkout
Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the Create a checkout
endpoint.
Follow this request with Retrieve a checkout
to confirm its status.
Path Parameters
- id string required
Body Parameters
- card object
Required when payment type is
card
. Details of the payment card.CloseAttributes- cvv string required
Three or four-digit card verification value (security code) of the payment card.
Example:"123"
- expiry_month string requiredOptions:
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
. - expiry_year string required
Year from the expiration time of the payment card. Accepted formats are
YY
andYYYY
.Example:"2023"
- last_4_digits string required
Last 4 digits of the payment card number.
Example:"3456"
- 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"
- type string requiredOptions:
AMEX
CUP
DINERS
DISCOVER
ELO
ELV
HIPERCARD
JCB
MAESTRO
MASTERCARD
VISA
VISA_ELECTRON
VISA_VPAY
UNKNOWN
Issuing card network of the payment card.
- zip_code string
Required five-digit ZIP code. Applicable only to merchant users in the USA.
Example:"12345"
-
- customer_id string
Required when
token
is provided. Unique ID of the customer. - installments integer
Number of installments for deferred payments. Available only to merchant users in Brazil.
- mandate object
Mandate is passed when a card is to be tokenised
CloseAttributes- type string requiredOptions:
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"}
-
- payment_type string requiredOptions:
card
boleto
ideal
blik
bancontact
- token string
Required when using a tokenized card to process a checkout. Unique token identifying the saved payment card for a customer.
Response 200
- amount number
Amount of the payment.
Example:10.1
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.
Example:"831ff8d4cd5958ab5670"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
Example:"4e425463-3e1b-431d-83fa-1e51c2925e99"
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- merchant_code string
Unique identifying code of the merchant profile.
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made.
- return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
- status stringOptions:
PENDING
FAILED
PAID
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
- merchant_name string
Name of the merchant
Example:"Sample Merchant"
- payment_instrument object
Object containing token information for the specified payment instrument
CloseAttributes- token string
Token value
Example:"e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
-
- redirect_url string
Refers to a url where the end user is redirected once the payment processing completes.
Example:"https://mysite.com/completed_purchase"
- transaction_code string
Transaction code of the successful transaction with which the payment for the checkout is completed.
Example:"TEENSK4W2K"
- transaction_id string
Transaction ID of the successful transaction with which the payment for the checkout is completed.
Example:"410fc44a-5956-44e1-b5cc-19c6f8d727a4"
Response 400
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 409
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/checkouts/{id}
{
"next_step": {
"full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
"mechanism": [
"browser"
],
"method": "GET",
"payload": {
"cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
"rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
"tx": "624788471"
},
"url": "https://r3.girogate.de/ti/simbcmc"
}
}
{
"amount": 10.1,
"boleto": {
"barcode": "34191090081790614310603072340007886840000000200",
"url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
},
"checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
"currency": "BRL",
"date": "2021-07-06T12:34:02.000+00:00",
"description": "Boleto checkout",
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"merchant_code": "MH4H92C7",
"merchant_name": "Sample shop",
"pay_to_email": "user@example.com",
"purpose": "CHECKOUT",
"redirect_url": "https://website.com",
"status": "PENDING",
"transactions": [
{
"amount": 10.1,
"currency": "BRL",
"entry_mode": "BOLETO",
"id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
"installments_count": 1,
"internal_id": 1763892018,
"merchant_code": "MH4H92C9",
"payment_type": "BOLETO",
"status": "PENDING",
"timestamp": "2021-07-06T12:34:16.460+00:00",
"tip_amount": 3,
"transaction_code": "TEN3E696NP",
"vat_amount": 6
}
]
}
{
"amount": 10.1,
"checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": "Purchase",
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"merchant_code": "MH4H92C7",
"pay_to_email": "user@example.com",
"return_url": "http://example.com",
"status": "PENDING",
"transaction_code": "TEENSK4W2K",
"transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"transactions": [
{
"amount": 10.1,
"auth_code": "053201",
"currency": "EUR",
"entry_mode": "CUSTOMER_ENTRY",
"id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"installments_count": 1,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"payment_type": "ECOM",
"status": "SUCCESSFUL",
"timestamp": "2020-02-29T10:56:56.876Z",
"tip_amount": 3,
"transaction_code": "TEENSK4W2K",
"vat_amount": 6
}
],
"valid_until": "2020-02-29T10:56:56+00:00"
}
{
"amount": 10.1,
"checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
"currency": "EUR",
"customer_id": "831ff8d4cd5958ab5670",
"date": "2020-02-29T10:56:56+00:00",
"description": "Purchase with token",
"id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
"merchant_code": "MH4H92C7",
"merchant_name": "Sample Merchant",
"pay_to_email": "user@example.com",
"payment_instrument": {
"token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
},
"redirect_url": "https://mysite.com/completed_purchase",
"status": "PENDING",
"transaction_code": "TEENSK4W2K",
"transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"transactions": [
{
"amount": 10.1,
"auth_code": "053201",
"currency": "EUR",
"entry_mode": "CUSTOMER_ENTRY",
"id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
"installments_count": 1,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"payment_type": "ECOM",
"status": "SUCCESSFUL",
"timestamp": "2020-02-29T10:56:56.876Z",
"tip_amount": 3,
"transaction_code": "TEENSK4W2K",
"vat_amount": 6
}
]
}
{
"next_step": {
"full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
"mechanism": [
"browser"
],
"method": "GET",
"payload": {
"cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
"rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
"tx": "961473700"
},
"url": "https://r3.girogate.de/ti/simideal"
}
}
Deactivate a checkout
Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.
payments
Path Parameters
- id string required
Response 200
- amount number
Amount of the payment.
- checkout_reference string
Unique ID of the payment checkout specified by the client application when creating the checkout resource.
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- date string
Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56+00:00"
- description string
Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.
- id string
Unique ID of the checkout resource.
- merchant_code string
Unique identifying code of the merchant profile.
- merchant_country string
The merchant's country
- merchant_name string
Merchant name
- pay_to_email string
Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use
merchant_code
instead ofpay_to_email
. - purpose stringOptions:
SETUP_RECURRING_PAYMENT
CHECKOUT
Purpose of the checkout creation initially
- status stringOptions:
EXPIRED
Current status of the checkout.
- transactions []object
List of transactions related to the payment.
CloseAttributes- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
-
- valid_until string
Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.
Example:"2020-02-29T10:56:56+00:00"
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 409
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/checkouts/{id}
{
"amount": 2,
"checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
"currency": "EUR",
"date": "2020-02-29T10:56:56+00:00",
"description": "Deletion example",
"id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
"merchant_code": "MH4H92C7",
"merchant_name": "Sample Merchant",
"pay_to_email": "user@example.com",
"purpose": "CHECKOUT",
"status": "EXPIRED",
"transactions": [],
"valid_until": "2020-02-29T10:56:56+00:00"
}
Get available payment methods
Get payment methods available for the given merchant to use with a checkout.
payments
Path Parameters
- merchant_code string requiredExample:
M1234
Query Parameters
- amount numberExample:
9.99
- currency stringExample:
EUR
Response 200
- available_payment_methods []objectCloseAttributes
- id string required
The ID of the payment method.
Example:"qr_code_pix"
-
Response 400
- details string
Details of the error.
- failed_constraints []objectCloseAttributes
- message string
- reference string
-
- status number
The status code.
- title string
Short title of the error.
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods
{
"available_payment_methods": [
{
"id": "apple_pay"
},
{
"id": "blik"
}
]
}
Customers
Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform.
Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.
The Customer object
Attributes
- customer_id string required
Unique ID of the customer.
Example:"831ff8d4cd5958ab5670"
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
{
"customer_id": "831ff8d4cd5958ab5670",
"personal_details": {
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Sample street",
"line2": "ap. 5",
"postal_code": "10115",
"state": "Berlin"
},
"birthdate": "1993-12-31",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+491635559723"
}
}
Create a customer
Creates a new saved customer resource which you can later manipulate and save payment instruments to.
payment_instruments
Body Parameters
- customer_id string required
Unique ID of the customer.
Example:"831ff8d4cd5958ab5670"
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
Response 201
- customer_id string required
Unique ID of the customer.
Example:"831ff8d4cd5958ab5670"
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 409
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/customers
{
"customer_id": "831ff8d4cd5958ab5670",
"personal_details": {
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Sample street",
"line2": "ap. 5",
"postal_code": "10115",
"state": "Berlin"
},
"birthdate": "1993-12-31",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+491635559723"
}
}
Retrieve a customer
Retrieves an identified saved customer resource through the unique customer_id
parameter, generated upon customer creation.
payment_instruments
Path Parameters
- customer_id string required
Response 200
- customer_id string required
Unique ID of the customer.
Example:"831ff8d4cd5958ab5670"
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/customers/{customer_id}
{
"customer_id": "831ff8d4cd5958ab5670",
"personal_details": {
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Sample street",
"line2": "ap. 5",
"postal_code": "10115",
"state": "Berlin"
},
"birthdate": "1993-12-31",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+491635559723"
}
}
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.
payment_instruments
Path Parameters
- customer_id string required
Body Parameters
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
Response 200
- customer_id string required
Unique ID of the customer.
Example:"831ff8d4cd5958ab5670"
- personal_details object
Personal details for the customer.
CloseAttributes- address object
Profile's personal address information.
CloseAttributes- city string
City name from the address.
Example:"Berlin"
- country string required
Two letter country code formatted according to ISO3166-1 alpha-2.
Example:"DE"
- line1 string
First line of the address with details of the street name and number.
Example:"Sample street"
- line2 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"
-
- birthdate string
Date of birth of the customer.
Example:"1993-12-31"
- email string
Email address of the customer.
Example:"user@example.com"
- first_name string
First name of the customer.
Example:"John"
- last_name string
Last name of the customer.
Example:"Doe"
- phone string
Phone number of the customer.
Example:"+491635559723"
-
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/customers/{customer_id}
{
"customer_id": "831ff8d4cd5958ab5670",
"personal_details": {
"address": {
"city": "Berlin",
"country": "DE",
"line1": "Sample street",
"line2": "ap. 5",
"postal_code": "10115",
"state": "Berlin"
},
"birthdate": "1993-12-31",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "+491635559723"
}
}
List payment instruments
Lists all payment instrument resources that are saved for an identified customer.
payment_instruments
Path Parameters
- customer_id string required
Response 200
- active boolean
Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a
DELETE
request to the resource endpoint. - card object
Details of the payment card.
CloseAttributes- last_4_digits string
Last 4 digits of the payment card number.
Example:"3456"
- type stringOptions:
AMEX
CUP
DINERS
DISCOVER
ELO
ELV
HIPERCARD
JCB
MAESTRO
MASTERCARD
VISA
VISA_ELECTRON
VISA_VPAY
UNKNOWN
Issuing card network of the payment card.
-
- created_at string
Creation date of payment instrument. Response format expressed according to ISO8601 code.
- mandate object
Created mandate
CloseAttributes- merchant_code string
Merchant code which has the mandate
- status string
Mandate status
- type string
Indicates the mandate type
Example:{"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
-
- token string
Unique token identifying the saved payment card for a customer.
- type stringOptions:
card
Type of the payment instrument.
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments
[
{
"active": true,
"card": {
"last_4_digits": "0001",
"type": "VISA"
},
"created_at": "2021-03-30T10:06:07.000+00:00",
"mandate": {
"merchant_code": "MDASYTPD",
"status": "active",
"type": "recurrent"
},
"token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
"type": "card"
}
]
Deactivate a payment instrument
Deactivates an identified card payment instrument resource for a customer.
payment_instruments
Path Parameters
- customer_id string required
- token string required
Response 204
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token}
{}
Merchant
Manage merchant profile.
The Merchant Account object
Details of the merchant account.
Attributes
- account object
Profile information.
CloseAttributes- type stringOptions:
normal
operator
The role of the user.
- username string
Username of the user profile.
-
- app_settings object
Mobile app settings
CloseAttributes- advanced_mode string
Advanced mode.
- barcode_scanner string
Barcode scanner.
- cash_payment string
Cash payment.
- checkout_preference string
Checkout preference
- expected_max_transaction_amount number
Expected max transaction amount.
- include_vat boolean
Include vat.
- manual_entry string
Manual entry.
- manual_entry_tutorial boolean
Manual entry tutorial.
- mobile_payment string
Mobile payment.
- mobile_payment_tutorial boolean
Mobile payment tutorial.
- reader_payment string
Reader payment.
- referral string
Referral.
- tax_enabled boolean
Tax enabled.
- terminal_mode_tutorial boolean
Terminal mode tutorial.
- tip_rates []number
Tip rates.
CloseAttributes - tipping string
Tipping.
-
- is_migrated_payleven_br boolean
Merchant comes from payleven BR migration
- merchant_profile object
Account's merchant profile
CloseAttributes- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- bank_accounts []objectCloseAttributes
- account_category string
Account category - business or personal
- account_holder_name string
- account_number string
Account number
- account_type string
Type of the account
- bank_code string
Bank code
- bank_name string
Bank name
- branch_code string
Branch code
- created_at string
Creation date of the bank account
- iban string
IBAN
- primary boolean
The primary bank account is the one used for settlements
- status string
Status in the verification process
- swift string
SWIFT code
-
- business_owners []object
Business owners information.
- company_name string
Company name
- company_registration_number string
Company registration number
- country string
Merchant country isocode (for internal usage only)
- doing_business_as object
Doing Business As information
CloseAttributes- address objectCloseAttributes
- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- country string
Country ISO 3166-1 code
- post_code string
Postal code
- region_id number
Country region ID
- region_name string
Country region name
-
- business_name string
Doing business as name
- company_registration_number string
Doing business as company registration number
- email string
Doing business as email
- vat_id string
Doing business as VAT ID
- website string
Doing business as website
-
- extdev boolean
True if the merchant is extdev
- legal_type object
Id of the legal type of the merchant profile
CloseAttributes- description string
Legal type short description
- full_description string
Legal type description
- id number
Unique id
- sole_trader boolean
Sole trader legal type if true
-
- locale string
Merchant locale (for internal usage only)
- merchant_category_code string
Merchant category code
- merchant_code string
Unique identifying code of the merchant profile
- mobile_phone string
Mobile phone number
- nature_and_purpose string
Nature and purpose of the business
- payout_zone_migrated boolean
True if the payout zone of this merchant is migrated
- permanent_certificate_access_code string
Permanent certificate access code (Portugal)
- settings object
Merchant settings (like "payout_type", "payout_period")
CloseAttributes- daily_payout_email boolean
Whether merchant will receive daily payout emails
- gross_settlement boolean
Whether merchant has gross settlement enabled
- monthly_payout_email boolean
Whether merchant will receive monthly payout emails
- moto_payment stringOptions:
UNAVAILABLE
ENFORCED
ON
OFF
Whether merchant can make MOTO payments
- payout_instrument string
Payout Instrument
- payout_on_demand boolean
Whether merchant will receive payouts on demand
- payout_on_demand_available boolean
Whether merchant can edit payouts on demand
- payout_period string
Payout frequency
- payout_type string
Payout type
- printers_enabled boolean
Whether to show printers in mobile app
- stone_merchant_code string
Stone merchant code
- tax_enabled boolean
Whether to show tax in receipts (saved per transaction)
-
- vat_id string
Vat ID
- vat_rates object
Merchant VAT rates
CloseAttributes- country string
Country ISO code
- description string
Description
- id number
Internal ID
- ordering number
Ordering
- rate number
Rate
-
- website string
Website
-
- permissions object
User permissions
CloseAttributes- create_moto_payments boolean
Create MOTO payments
- create_referral boolean
Create referral
- full_transaction_history_view boolean
Can view full merchant transaction history
- refund_transactions boolean
Refund transactions
-
- personal_profile object
Account's personal profile.
CloseAttributes- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- complete boolean
- date_of_birth string
Date of birth
- first_name string
First name of the user
- last_name string
Last name of the user
- mobile_phone string
Mobile phone number
-
{
"account": {
"type": null,
"username": null
},
"app_settings": {
"advanced_mode": null,
"barcode_scanner": null,
"cash_payment": null,
"checkout_preference": null,
"expected_max_transaction_amount": null,
"include_vat": null,
"manual_entry": null,
"manual_entry_tutorial": null,
"mobile_payment": null,
"mobile_payment_tutorial": null,
"reader_payment": null,
"referral": null,
"tax_enabled": null,
"terminal_mode_tutorial": null,
"tip_rates": [
null
],
"tipping": null
},
"is_migrated_payleven_br": null,
"merchant_profile": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"bank_accounts": [
{
"account_category": null,
"account_holder_name": null,
"account_number": null,
"account_type": null,
"bank_code": null,
"bank_name": null,
"branch_code": null,
"created_at": null,
"iban": null,
"primary": null,
"status": null,
"swift": null
}
],
"business_owners": [
{
"date_of_birth": null,
"first_name": null,
"landline": null,
"last_name": null,
"mobile_phone": null,
"ownership": null
}
],
"company_name": null,
"company_registration_number": null,
"country": null,
"doing_business_as": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"country": null,
"post_code": null,
"region_id": null,
"region_name": null
},
"business_name": null,
"company_registration_number": null,
"email": null,
"vat_id": null,
"website": null
},
"extdev": null,
"legal_type": {
"description": null,
"full_description": null,
"id": null,
"sole_trader": null
},
"locale": null,
"merchant_category_code": null,
"merchant_code": null,
"mobile_phone": null,
"nature_and_purpose": null,
"payout_zone_migrated": null,
"permanent_certificate_access_code": null,
"settings": {
"daily_payout_email": null,
"gross_settlement": null,
"monthly_payout_email": null,
"moto_payment": null,
"payout_instrument": null,
"payout_on_demand": null,
"payout_on_demand_available": null,
"payout_period": null,
"payout_type": null,
"printers_enabled": null,
"stone_merchant_code": null,
"tax_enabled": null
},
"vat_id": null,
"vat_rates": {
"country": null,
"description": null,
"id": null,
"ordering": null,
"rate": null
},
"website": null
},
"permissions": {
"create_moto_payments": null,
"create_referral": null,
"full_transaction_history_view": null,
"refund_transactions": null
},
"personal_profile": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"complete": null,
"date_of_birth": null,
"first_name": null,
"last_name": null,
"mobile_phone": null
}
}
Retrieve a profile
Returns user profile information.
user.profile
user.profile_readonly
Query Parameters
- include[] []string
Response 200
- account object
Profile information.
CloseAttributes- type stringOptions:
normal
operator
The role of the user.
- username string
Username of the user profile.
-
- app_settings object
Mobile app settings
CloseAttributes- advanced_mode string
Advanced mode.
- barcode_scanner string
Barcode scanner.
- cash_payment string
Cash payment.
- checkout_preference string
Checkout preference
- expected_max_transaction_amount number
Expected max transaction amount.
- include_vat boolean
Include vat.
- manual_entry string
Manual entry.
- manual_entry_tutorial boolean
Manual entry tutorial.
- mobile_payment string
Mobile payment.
- mobile_payment_tutorial boolean
Mobile payment tutorial.
- reader_payment string
Reader payment.
- referral string
Referral.
- tax_enabled boolean
Tax enabled.
- terminal_mode_tutorial boolean
Terminal mode tutorial.
- tip_rates []number
Tip rates.
CloseAttributes - tipping string
Tipping.
-
- is_migrated_payleven_br boolean
Merchant comes from payleven BR migration
- merchant_profile object
Account's merchant profile
CloseAttributes- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- bank_accounts []objectCloseAttributes
- account_category string
Account category - business or personal
- account_holder_name string
- account_number string
Account number
- account_type string
Type of the account
- bank_code string
Bank code
- bank_name string
Bank name
- branch_code string
Branch code
- created_at string
Creation date of the bank account
- iban string
IBAN
- primary boolean
The primary bank account is the one used for settlements
- status string
Status in the verification process
- swift string
SWIFT code
-
- business_owners []object
Business owners information.
- company_name string
Company name
- company_registration_number string
Company registration number
- country string
Merchant country isocode (for internal usage only)
- doing_business_as object
Doing Business As information
CloseAttributes- address objectCloseAttributes
- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- country string
Country ISO 3166-1 code
- post_code string
Postal code
- region_id number
Country region ID
- region_name string
Country region name
-
- business_name string
Doing business as name
- company_registration_number string
Doing business as company registration number
- email string
Doing business as email
- vat_id string
Doing business as VAT ID
- website string
Doing business as website
-
- extdev boolean
True if the merchant is extdev
- legal_type object
Id of the legal type of the merchant profile
CloseAttributes- description string
Legal type short description
- full_description string
Legal type description
- id number
Unique id
- sole_trader boolean
Sole trader legal type if true
-
- locale string
Merchant locale (for internal usage only)
- merchant_category_code string
Merchant category code
- merchant_code string
Unique identifying code of the merchant profile
- mobile_phone string
Mobile phone number
- nature_and_purpose string
Nature and purpose of the business
- payout_zone_migrated boolean
True if the payout zone of this merchant is migrated
- permanent_certificate_access_code string
Permanent certificate access code (Portugal)
- settings object
Merchant settings (like "payout_type", "payout_period")
CloseAttributes- daily_payout_email boolean
Whether merchant will receive daily payout emails
- gross_settlement boolean
Whether merchant has gross settlement enabled
- monthly_payout_email boolean
Whether merchant will receive monthly payout emails
- moto_payment stringOptions:
UNAVAILABLE
ENFORCED
ON
OFF
Whether merchant can make MOTO payments
- payout_instrument string
Payout Instrument
- payout_on_demand boolean
Whether merchant will receive payouts on demand
- payout_on_demand_available boolean
Whether merchant can edit payouts on demand
- payout_period string
Payout frequency
- payout_type string
Payout type
- printers_enabled boolean
Whether to show printers in mobile app
- stone_merchant_code string
Stone merchant code
- tax_enabled boolean
Whether to show tax in receipts (saved per transaction)
-
- vat_id string
Vat ID
- vat_rates object
Merchant VAT rates
CloseAttributes- country string
Country ISO code
- description string
Description
- id number
Internal ID
- ordering number
Ordering
- rate number
Rate
-
- website string
Website
-
- permissions object
User permissions
CloseAttributes- create_moto_payments boolean
Create MOTO payments
- create_referral boolean
Create referral
- full_transaction_history_view boolean
Can view full merchant transaction history
- refund_transactions boolean
Refund transactions
-
- personal_profile object
Account's personal profile.
CloseAttributes- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- complete boolean
- date_of_birth string
Date of birth
- first_name string
First name of the user
- last_name string
Last name of the user
- mobile_phone string
Mobile phone number
-
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me
{
"account": {
"type": null,
"username": null
},
"app_settings": {
"advanced_mode": null,
"barcode_scanner": null,
"cash_payment": null,
"checkout_preference": null,
"expected_max_transaction_amount": null,
"include_vat": null,
"manual_entry": null,
"manual_entry_tutorial": null,
"mobile_payment": null,
"mobile_payment_tutorial": null,
"reader_payment": null,
"referral": null,
"tax_enabled": null,
"terminal_mode_tutorial": null,
"tip_rates": [
null
],
"tipping": null
},
"is_migrated_payleven_br": null,
"merchant_profile": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"bank_accounts": [
{
"account_category": null,
"account_holder_name": null,
"account_number": null,
"account_type": null,
"bank_code": null,
"bank_name": null,
"branch_code": null,
"created_at": null,
"iban": null,
"primary": null,
"status": null,
"swift": null
}
],
"business_owners": [
{
"date_of_birth": null,
"first_name": null,
"landline": null,
"last_name": null,
"mobile_phone": null,
"ownership": null
}
],
"company_name": null,
"company_registration_number": null,
"country": null,
"doing_business_as": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"country": null,
"post_code": null,
"region_id": null,
"region_name": null
},
"business_name": null,
"company_registration_number": null,
"email": null,
"vat_id": null,
"website": null
},
"extdev": null,
"legal_type": {
"description": null,
"full_description": null,
"id": null,
"sole_trader": null
},
"locale": null,
"merchant_category_code": null,
"merchant_code": null,
"mobile_phone": null,
"nature_and_purpose": null,
"payout_zone_migrated": null,
"permanent_certificate_access_code": null,
"settings": {
"daily_payout_email": null,
"gross_settlement": null,
"monthly_payout_email": null,
"moto_payment": null,
"payout_instrument": null,
"payout_on_demand": null,
"payout_on_demand_available": null,
"payout_period": null,
"payout_type": null,
"printers_enabled": null,
"stone_merchant_code": null,
"tax_enabled": null
},
"vat_id": null,
"vat_rates": {
"country": null,
"description": null,
"id": null,
"ordering": null,
"rate": null
},
"website": null
},
"permissions": {
"create_moto_payments": null,
"create_referral": null,
"full_transaction_history_view": null,
"refund_transactions": null
},
"personal_profile": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"complete": null,
"date_of_birth": null,
"first_name": null,
"last_name": null,
"mobile_phone": null
}
}
Retrieve a merchant profile
Retrieves merchant profile data.
user.profile
user.profile_readonly
Response 200
- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- bank_accounts []objectCloseAttributes
- account_category string
Account category - business or personal
- account_holder_name string
- account_number string
Account number
- account_type string
Type of the account
- bank_code string
Bank code
- bank_name string
Bank name
- branch_code string
Branch code
- created_at string
Creation date of the bank account
- iban string
IBAN
- primary boolean
The primary bank account is the one used for settlements
- status string
Status in the verification process
- swift string
SWIFT code
-
- business_owners []object
Business owners information.
- company_name string
Company name
- company_registration_number string
Company registration number
- country string
Merchant country isocode (for internal usage only)
- doing_business_as object
Doing Business As information
CloseAttributes- address objectCloseAttributes
- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- country string
Country ISO 3166-1 code
- post_code string
Postal code
- region_id number
Country region ID
- region_name string
Country region name
-
- business_name string
Doing business as name
- company_registration_number string
Doing business as company registration number
- email string
Doing business as email
- vat_id string
Doing business as VAT ID
- website string
Doing business as website
-
- extdev boolean
True if the merchant is extdev
- legal_type object
Id of the legal type of the merchant profile
CloseAttributes- description string
Legal type short description
- full_description string
Legal type description
- id number
Unique id
- sole_trader boolean
Sole trader legal type if true
-
- locale string
Merchant locale (for internal usage only)
- merchant_category_code string
Merchant category code
- merchant_code string
Unique identifying code of the merchant profile
- mobile_phone string
Mobile phone number
- nature_and_purpose string
Nature and purpose of the business
- payout_zone_migrated boolean
True if the payout zone of this merchant is migrated
- permanent_certificate_access_code string
Permanent certificate access code (Portugal)
- settings object
Merchant settings (like "payout_type", "payout_period")
CloseAttributes- daily_payout_email boolean
Whether merchant will receive daily payout emails
- gross_settlement boolean
Whether merchant has gross settlement enabled
- monthly_payout_email boolean
Whether merchant will receive monthly payout emails
- moto_payment stringOptions:
UNAVAILABLE
ENFORCED
ON
OFF
Whether merchant can make MOTO payments
- payout_instrument string
Payout Instrument
- payout_on_demand boolean
Whether merchant will receive payouts on demand
- payout_on_demand_available boolean
Whether merchant can edit payouts on demand
- payout_period string
Payout frequency
- payout_type string
Payout type
- printers_enabled boolean
Whether to show printers in mobile app
- stone_merchant_code string
Stone merchant code
- tax_enabled boolean
Whether to show tax in receipts (saved per transaction)
-
- vat_id string
Vat ID
- vat_rates object
Merchant VAT rates
CloseAttributes- country string
Country ISO code
- description string
Description
- id number
Internal ID
- ordering number
Ordering
- rate number
Rate
-
- website string
Website
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
curl https://api.sumup.com/v0.1/me/merchant-profile
{
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"bank_accounts": [
{
"account_category": null,
"account_holder_name": null,
"account_number": null,
"account_type": null,
"bank_code": null,
"bank_name": null,
"branch_code": null,
"created_at": null,
"iban": null,
"primary": null,
"status": null,
"swift": null
}
],
"business_owners": [
{
"date_of_birth": null,
"first_name": null,
"landline": null,
"last_name": null,
"mobile_phone": null,
"ownership": null
}
],
"company_name": null,
"company_registration_number": null,
"country": null,
"doing_business_as": {
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"country": null,
"post_code": null,
"region_id": null,
"region_name": null
},
"business_name": null,
"company_registration_number": null,
"email": null,
"vat_id": null,
"website": null
},
"extdev": null,
"legal_type": {
"description": null,
"full_description": null,
"id": null,
"sole_trader": null
},
"locale": null,
"merchant_category_code": null,
"merchant_code": null,
"mobile_phone": null,
"nature_and_purpose": null,
"payout_zone_migrated": null,
"permanent_certificate_access_code": null,
"settings": {
"daily_payout_email": null,
"gross_settlement": null,
"monthly_payout_email": null,
"moto_payment": null,
"payout_instrument": null,
"payout_on_demand": null,
"payout_on_demand_available": null,
"payout_period": null,
"payout_type": null,
"printers_enabled": null,
"stone_merchant_code": null,
"tax_enabled": null
},
"vat_id": null,
"vat_rates": {
"country": null,
"description": null,
"id": null,
"ordering": null,
"rate": null
},
"website": null
}
Retrieve a personal profile
Retrieves personal profile data.
user.profile
user.profile_readonly
Response 200
- address object
Details of the registered address.
CloseAttributes- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- company string
undefined
- country string
Country ISO 3166-1 code
- country_details object
Country Details
CloseAttributes- currency string
Currency ISO 4217 code
- en_name string
Country EN name
- iso_code string
Country ISO code
- native_name string
Country native name
-
- first_name string
undefined
- landline string
Landline number
- last_name string
undefined
- post_code string
Postal code
- region_code string
Region code
- region_id number
Country region id
- region_name string
Region name
- state_id string
undefined
- timeoffset_details object
TimeOffset Details
CloseAttributes- dst boolean
Daylight Saving Time
- offset number
UTC offset
- post_code string
Postal code
-
-
- complete boolean
- date_of_birth string
Date of birth
- first_name string
First name of the user
- last_name string
Last name of the user
- mobile_phone string
Mobile phone number
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/personal-profile
{
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"company": null,
"country": null,
"country_details": {
"currency": null,
"en_name": null,
"iso_code": null,
"native_name": null
},
"first_name": null,
"landline": null,
"last_name": null,
"post_code": null,
"region_code": null,
"region_id": null,
"region_name": null,
"state_id": null,
"timeoffset_details": {
"dst": null,
"offset": null,
"post_code": null
}
},
"complete": null,
"date_of_birth": null,
"first_name": null,
"last_name": null,
"mobile_phone": null
}
Response 200
- daily_payout_email boolean
Whether merchant will receive daily payout emails
- gross_settlement boolean
Whether merchant has gross settlement enabled
- monthly_payout_email boolean
Whether merchant will receive monthly payout emails
- moto_payment stringOptions:
UNAVAILABLE
ENFORCED
ON
OFF
Whether merchant can make MOTO payments
- payout_instrument string
Payout Instrument
- payout_on_demand boolean
Whether merchant will receive payouts on demand
- payout_on_demand_available boolean
Whether merchant can edit payouts on demand
- payout_period string
Payout frequency
- payout_type string
Payout type
- printers_enabled boolean
Whether to show printers in mobile app
- stone_merchant_code string
Stone merchant code
- tax_enabled boolean
Whether to show tax in receipts (saved per transaction)
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
curl https://api.sumup.com/v0.1/me/merchant-profile/settings
{
"daily_payout_email": null,
"gross_settlement": null,
"monthly_payout_email": null,
"moto_payment": null,
"payout_instrument": null,
"payout_on_demand": null,
"payout_on_demand_available": null,
"payout_period": null,
"payout_type": null,
"printers_enabled": null,
"stone_merchant_code": null,
"tax_enabled": null
}
List bank accounts
Retrives bank accounts of the merchant.
user.payout-settings
user.profile
user.profile_readonly
Query Parameters
- primary boolean
Response 200
- account_category string
Account category - business or personal
- account_holder_name string
- account_number string
Account number
- account_type string
Type of the account
- bank_code string
Bank code
- bank_name string
Bank name
- branch_code string
Branch code
- created_at string
Creation date of the bank account
- iban string
IBAN
- primary boolean
The primary bank account is the one used for settlements
- status string
Status in the verification process
- swift string
SWIFT code
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 403
- error_code string
Platform code for the error.
- error_message string
Short description of the error.
- status_code string
HTTP status code for the error.
curl https://api.sumup.com/v0.1/me/merchant-profile/bank-accounts
[
{
"account_category": null,
"account_holder_name": null,
"account_number": null,
"account_type": null,
"bank_code": null,
"bank_name": null,
"branch_code": null,
"created_at": null,
"iban": null,
"primary": null,
"status": null,
"swift": null
}
]
Retrieve DBA
Retrieves Doing Business As profile.
user.profile
user.profile_readonly
Response 200
- address objectCloseAttributes
- address_line1 string
Address line 1
- address_line2 string
Address line 2
- city string
City
- country string
Country ISO 3166-1 code
- post_code string
Postal code
- region_id number
Country region ID
- region_name string
Country region name
-
- business_name string
Doing business as name
- company_registration_number string
Doing business as company registration number
- email string
Doing business as email
- vat_id string
Doing business as VAT ID
- website string
Doing business as website
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as
{
"address": {
"address_line1": null,
"address_line2": null,
"city": null,
"country": null,
"post_code": null,
"region_id": null,
"region_name": null
},
"business_name": null,
"company_registration_number": null,
"email": null,
"vat_id": null,
"website": null
}
Subaccounts
Endpoints for managing merchant sub-accounts (operators).
The object
Attributes
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
List operators.
Deprecated
Returns list of operators for currently authorized user's merchant.
Query Parameters
- query string
- include_primary boolean
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
curl https://api.sumup.com/v0.1/me/accounts
[
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
]
Create operator.
Deprecated
Creates new operator for currently authorized users' merchant.
Body Parameters
- nickname stringExample:
"Operator 1"
- password string requiredExample:
"correct horse batter staple"
- permissions objectCloseAttributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean
-
- username string requiredExample:
"operator1@mydomain.com"
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
Response 403
- error_code string requiredExample:
"NOT_FOUND"
- message string requiredExample:
"Resource not found."
curl https://api.sumup.com/v0.1/me/accounts
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
Path Parameters
- operator_id integer required
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
Update operator.
Deprecated
Updates operator. If the operator was disabled and their password is updated they will be unblocked.
Path Parameters
- operator_id integer required
Body Parameters
- disabled boolean
- nickname stringExample:
"Operator 1"
- password stringExample:
"correct horse batter staple"
- permissions objectCloseAttributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean
-
- username string
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
Response 400
- error_code string requiredExample:
"NOT_FOUND"
- message string requiredExample:
"Resource not found."
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
Path Parameters
- operator_id integer required
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
Change operators password.
Deprecated
Changes operators password, if the operator was disabled they will be unblocked.
Path Parameters
- operator_id integer required
Body Parameters
- password stringExample:
"correct horse batter staple"
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
Response 400
- error_code string requiredExample:
"NOT_FOUND"
- message string requiredExample:
"Resource not found."
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/reset
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
Path Parameters
- operator_id integer required
Response 200
- account_type string requiredOptions:
operator
normal
- created_at string required
- disabled boolean required
- id integer required
- nickname stringExample:
"Operator 1"
- permissions object requiredCloseAttributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
-
- updated_at string required
- username string requiredExample:
"operator1@mydomain.com"
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/disable
{
"account_type": "",
"created_at": "",
"disabled": false,
"id": 0,
"nickname": "Operator 1",
"permissions": {
"admin": false,
"create_moto_payments": false,
"create_referral": false,
"full_transaction_history_view": false,
"refund_transactions": false
},
"updated_at": "",
"username": "operator1@mydomain.com"
}
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
Attributes
- amount number
- currency string
- date string
- fee number
- id integer
- reference string
- status stringOptions:
SUCCESSFUL
FAILED
- transaction_code string
- type stringOptions:
PAYOUT
CHARGE_BACK_DEDUCTION
REFUND_DEDUCTION
DD_RETURN_DEDUCTION
BALANCE_DEDUCTION
[
{
"amount": null,
"currency": null,
"date": null,
"fee": null,
"id": null,
"reference": null,
"status": null,
"transaction_code": null,
"type": null
}
]
List payouts
Lists ordered payouts for the merchant profile.
user.profile
user.profile_readonly
Query Parameters
- start_date string required
- end_date string required
- format string
- limit integer
- order string
Response 200
- amount number
- currency string
- date string
- fee number
- id integer
- reference string
- status stringOptions:
SUCCESSFUL
FAILED
- transaction_code string
- type stringOptions:
PAYOUT
CHARGE_BACK_DEDUCTION
REFUND_DEDUCTION
DD_RETURN_DEDUCTION
BALANCE_DEDUCTION
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/financials/payouts
[
{
"amount": null,
"currency": null,
"date": null,
"fee": null,
"id": null,
"reference": null,
"status": null,
"transaction_code": null,
"type": null
}
]
Transactions
Retrieve details for a specific transaction by it’s id
or any other required query parameter, or list all transactions related to the merchant account.
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
transactions.history
Query Parameters
- id string
- internal_id string
- transaction_code string
Response 200
- amount number
Total amount of the transaction.
Example:10.1
- currency string
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
Example:"EUR"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- auth_code string
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:"053201"
- entry_mode stringOptions:
CUSTOMER_ENTRY
BOLETO
Entry mode of the payment details.
- internal_id integer
Internal unique ID of the transaction on the SumUp platform.
Example:1763892018
- merchant_code string
Unique code of the registered merchant to whom the payment is made.
Example:"MH4H92C7"
- tip_amount number
Amount of the tip (out of the total transaction amount).
Example:3
- vat_amount number
Amount of the applicable VAT (out of the total transaction amount).
Example:6
- payout_plan stringOptions:
SINGLE_PAYMENT
TRUE_INSTALLMENT
ACCELERATED_INSTALLMENT
Payout plan of the registered user at the time when the transaction was made.
- payouts_received integer
Number of payouts that are made to the registered user specified in the
user
property. - payouts_total integer
Total number of payouts to the registered user specified in the
user
property. - product_summary string
Short description of the payment. The value is taken from the
description
property of the related checkout resource. - card object
Details of the payment card.
CloseAttributes- last_4_digits string
Last 4 digits of the payment card number.
Example:"3456"
- type stringOptions:
AMEX
CUP
DINERS
DISCOVER
ELO
ELV
HIPERCARD
JCB
MAESTRO
MASTERCARD
VISA
VISA_ELECTRON
VISA_VPAY
UNKNOWN
Issuing card network of the payment card.
-
- events []object
List of events related to the transaction.
CloseAttributes- amount number
Amount of the event.
- deducted_amount number
Amount deducted for the event.
- deducted_fee_amount number
Amount of the fee deducted for the event.
- fee_amount number
Amount of the fee related to the event.
- id integer
Unique ID of the transaction event.
- installment_number integer
Consecutive number of the installment.
- status string
Status of the transaction event.
- timestamp string
Date and time of the transaction event.
- transaction_id string
Unique ID of the transaction.
- type string
Type of the transaction event.
-
- horizontal_accuracy number
Indication of the precision of the geographical position received from the payment terminal.
- lat number
Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
- links []object
List of hyperlinks for accessing related resources.
CloseAttributes - local_time string
Local date and time of the creation of the transaction.
- location object
Details of the payment location as received from the payment terminal.
CloseAttributes- horizontal_accuracy number
Indication of the precision of the geographical position received from the payment terminal.
- 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).
-
- lon number
Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
- payout_type stringOptions:
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.
CloseAttributes- name string
Name of the product from the merchant's catalog.
- price number
Price of the product without VAT.
- price_with_vat number
Price of a single product item with VAT.
- quantity number
Number of product items for the purchase.
- single_vat_amount number
Amount of the VAT for a single product item (calculated as the product of
price
andvat_rate
, i.e.single_vat_amount = price * vat_rate
). - total_price number
Total price of the product items without VAT (calculated as the product of
price
andquantity
, 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
andquantity
, i.e.total_with_vat = price_with_vat * quantity
). - vat_amount number
Total VAT amount for the purchase (calculated as the product of
single_vat_amount
andquantity
, i.e.vat_amount = single_vat_amount * quantity
). - vat_rate number
VAT rate applicable to the product.
-
- simple_payment_type stringOptions:
MOTO
CASH
CC_SIGNATURE
ELV
CC_CUSTOMER_ENTERED
MANUAL_ENTRY
EMV
Simple name of the payment type.
- simple_status stringOptions:
SUCCESSFUL
PAID_OUT
CANCEL_FAILED
CANCELLED
CHARGEBACK
FAILED
REFUND_FAILED
REFUNDED
NON_COLLECTION
Status generated from the processing status and the latest transaction state.
- tax_enabled boolean
Indicates whether tax deduction is enabled for the transaction.
- transaction_events []object
List of transaction events related to the transaction.
CloseAttributes- amount number
Amount of the event.
- date string
Date when the transaction event occurred.
- due_date string
Date when the transaction event is due to occur.
- event_type string
Type of the transaction event.
- id integer
Unique ID of the transaction event.
- installment_number integer
Consequtive number of the installment that is paid. Applicable only payout events, i.e.
event_type = PAYOUT
. - status string
Status of the transaction event.
- timestamp string
Date and time of the transaction event.
-
- username string
Email address of the registered user (merchant) to whom the payment is made.
- vat_rates []object
List of VAT rates applicable to the transaction.
CloseAttributes - verification_method stringOptions:
none
signature
offline pin
online pin
offline pin + signature
confirmation code verified
Verification method used for the transaction.
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/transactions
{
"amount": 10.1,
"currency": "EUR",
"id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
"installments_count": null,
"payment_type": null,
"status": null,
"timestamp": "2020-02-29T10:56:56.876Z",
"transaction_code": "TEENSK4W2K",
"auth_code": "053201",
"entry_mode": null,
"internal_id": 1763892018,
"merchant_code": "MH4H92C7",
"tip_amount": 3,
"vat_amount": 6,
"payout_plan": null,
"payouts_received": null,
"payouts_total": null,
"product_summary": null,
"card": {
"last_4_digits": "3456",
"type": null
},
"events": [
{
"amount": null,
"deducted_amount": null,
"deducted_fee_amount": null,
"fee_amount": null,
"id": null,
"installment_number": null,
"status": null,
"timestamp": null,
"transaction_id": null,
"type": null
}
],
"horizontal_accuracy": null,
"lat": null,
"links": [
null
],
"local_time": null,
"location": {
"horizontal_accuracy": null,
"lat": null,
"lon": null
},
"lon": null,
"payout_type": null,
"products": [
{
"name": null,
"price": null,
"price_with_vat": null,
"quantity": null,
"single_vat_amount": null,
"total_price": null,
"total_with_vat": null,
"vat_amount": null,
"vat_rate": null
}
],
"simple_payment_type": null,
"simple_status": null,
"tax_enabled": null,
"transaction_events": [
{
"amount": null,
"date": null,
"due_date": null,
"event_type": null,
"id": null,
"installment_number": null,
"status": null,
"timestamp": null
}
],
"username": null,
"vat_rates": [
null
],
"verification_method": null
}
Refund a transaction
Refunds an identified transaction either in full or partially.
payments
Path Parameters
- txn_id string required
Body Parameters
- amount number
Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.
Response 204
Response 404
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 409
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/refund/{txn_id}
{}
List transactions
Lists detailed history of all transactions associated with the merchant profile.
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 []objectCloseAttributes
- 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"
- id string
Unique ID of the transaction.
Example:"6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
Current number of the installment for deferred payments.
- payment_type stringOptions:
ECOM
RECURRING
BOLETO
Payment type used for the transaction.
- status stringOptions:
SUCCESSFUL
CANCELLED
FAILED
PENDING
Current status of the transaction.
- timestamp string
Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
Example:"2020-02-29T10:56:56.876Z"
- transaction_code string
Transaction code returned by the acquirer/processing entity after processing the transaction.
Example:"TEENSK4W2K"
- payout_plan stringOptions:
SINGLE_PAYMENT
TRUE_INSTALLMENT
ACCELERATED_INSTALLMENT
Payout plan of the registered user at the time when the transaction was made.
- payouts_received integer
Number of payouts that are made to the registered user specified in the
user
property. - payouts_total integer
Total number of payouts to the registered user specified in the
user
property. - product_summary string
Short description of the payment. The value is taken from the
description
property of the related checkout resource. - card_type stringOptions:
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.
- client_transaction_id string
Client-specific ID of the transaction.
- transaction_id string
Unique ID of the transaction.
- type stringOptions:
PAYMENT
REFUND
CHARGE_BACK
Type of the transaction for the registered user specified in the
user
property. - user string
Email address of the registered user (merchant) to whom the payment is made.
-
- links []objectCloseAttributes
- href string
URL for accessing the related resource.
- rel string
Specifies the relation to the current resource.
- type string
Specifies the media type of the related resource.
-
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v0.1/me/transactions/history
{
"items": [
{
"amount": 10.1,
"currency": "EUR",
"id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
"installments_count": null,
"payment_type": null,
"status": null,
"timestamp": "2020-02-29T10:56:56.876Z",
"transaction_code": "TEENSK4W2K",
"payout_plan": null,
"payouts_received": null,
"payouts_total": null,
"product_summary": null,
"card_type": null,
"client_transaction_id": null,
"transaction_id": null,
"type": null,
"user": null
}
],
"links": [
{
"href": null,
"rel": null,
"type": null
}
]
}
API Keys
API Keys allow your application to gain programmatic access to SumUp. API Keys allow application to do authorized requests within the SumUp ecosystem. API Keys are scopes to single account and thus can't be used for endpoints where user presence is needed (for such endpoints it is necessary to use OAuth2).
The API Key object
Attributes
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
Unique identifier of the API Key.
Example:"sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
User-assigned name of the API Key.
Example:"My API Key"
- plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example:"sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
Last 8 characters of the API key.
Example:"p6cL1vyZ"
- scopes []string required
- type string requiredOptions:
public
secret
Example:"secret"
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
{
"created_at": "2023-01-20T15:16:17Z",
"id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
"name": "My API Key",
"plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
"preview": "p6cL1vyZ",
"scopes": [
"invoices.read",
"invoices.write",
"products",
"user.app-settings"
],
"type": "secret",
"updated_at": "2023-01-20T15:16:17Z"
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Query Parameters
- offset integer0
- limit integerExample:
10
Response 200
- items []object requiredCloseAttributes
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
Unique identifier of the API Key.
Example:"sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
User-assigned name of the API Key.
Example:"My API Key"
- plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example:"sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
Last 8 characters of the API key.
Example:"p6cL1vyZ"
- scopes []string required
- type string requiredOptions:
public
secret
Example:"secret"
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- total_count integer required
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys
{
"items": [
{
"created_at": "2023-03-24T10:10:10Z",
"id": "sup_pk_1tpmgizNLHMkx1DdKd2hdzorZAaf6AcZ9",
"name": "",
"preview": "Aaf6AcZ9",
"scopes": [],
"type": "public",
"updated_at": "2023-03-24T10:10:10Z"
},
{
"created_at": "2023-03-25T09:10:10Z",
"id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
"name": "Test Key",
"preview": "TGhqew1b",
"scopes": [
"transactions.history",
"user.app-settings",
"user.profile_readonly",
"user.profile",
"user.subaccounts",
"user.payout-settings",
"products",
"payments",
"payment_instruments",
"readers.read",
"readers.write"
],
"type": "secret",
"updated_at": "2023-03-25T09:10:10Z"
}
],
"total_count": 2
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Body Parameters
- name string requiredExample:
"New Key Name"
- scopes []string required
Response 201
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
Unique identifier of the API Key.
Example:"sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
User-assigned name of the API Key.
Example:"My API Key"
- plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example:"sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
Last 8 characters of the API key.
Example:"p6cL1vyZ"
- scopes []string required
- type string requiredOptions:
public
secret
Example:"secret"
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys
{
"created_at": "2023-01-20T15:16:17Z",
"id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
"name": "My API Key",
"plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
"preview": "p6cL1vyZ",
"scopes": [
"invoices.read",
"invoices.write",
"products",
"user.app-settings"
],
"type": "secret",
"updated_at": "2023-01-20T15:16:17Z"
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- key_id string requiredExample:
sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9
Response 200
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
Unique identifier of the API Key.
Example:"sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
User-assigned name of the API Key.
Example:"My API Key"
- plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example:"sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
Last 8 characters of the API key.
Example:"p6cL1vyZ"
- scopes []string required
- type string requiredOptions:
public
secret
Example:"secret"
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}
{
"created_at": "2023-01-20T15:16:17Z",
"id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
"name": "My API Key",
"plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
"preview": "p6cL1vyZ",
"scopes": [
"invoices.read",
"invoices.write",
"products",
"user.app-settings"
],
"type": "secret",
"updated_at": "2023-01-20T15:16:17Z"
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- key_id string requiredExample:
sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9
Body Parameters
- name string required
New name for the API key.
Example:"My API Key"
- scopes []string required
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- key_id string requiredExample:
sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}
Collections
Endpoint to manage collections of files uploaded by merchant.
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/collections
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- collection_id string requiredExample:
123e4567-e89b-12d3-a456-426614174000
Body Parameters
- status string requiredExample:
"confirmed"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/collections/{collection_id}
Files
Endpoint to manage files uploaded by merchant.
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/files
Members
Preview feature
Endpoints to manage account members. Members are users that have membership within merchant accounts.
The Member object
A member is user within speicfic resource identified by resource id, resource type, and associated roles.
Attributes
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
ID of the member.
Example:"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- invite object
Pending invitation for membership.
CloseInvite- email string required
Email address of the invited user.
Example:"boaty.mcboatface@sumup.com"
- expires_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- permissions []string required
User's permissions.
CloseAttributes - roles []string required
User's roles.
CloseAttributes - status string required
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
- user object
User information.
CloseAttributes- classic object
Classic identifiers of the user.
CloseAttributes- user_id integer required
-
- disabled_at string
Time when the user has been disabled. Applies only to virtual users (
virtual_user: true
). - 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"
- id string required
Identifier for the End-User (also called Subject).
Example:"44ca0f5b-813b-46e1-aee7-e6242010662e"
- mfa_on_login_enabled boolean required
True if the user has enabled MFA on login.
Example:true
- nickname string
User's perferred 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"
- virtual_user boolean required
True if the user is a virtual user (operator).
-
{
"created_at": "2023-01-20T15:16:17Z",
"id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
"permissions": [
"members_read",
"members_write",
"create_moto_payments",
"full_transaction_history_view",
"refund_transactions",
"create_referral",
"developer_settings_write",
"developer_settings_read"
],
"roles": [
"role_admin",
"role_owner"
],
"status": "accepted",
"updated_at": "2023-02-20T15:16:17Z",
"user": {
"email": "example@sumup.com",
"id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
"mfa_on_login_enabled": true,
"virtual_user": false
}
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Query Parameters
- offset integer0
- limit integerExample:
10
- email stringExample:
user
- status string
- roles []stringExample:
role_employeerole_accountant
Response 200
- items []object requiredCloseAttributes
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
ID of the member.
Example:"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- invite object
Pending invitation for membership.
CloseInvite- email string required
Email address of the invited user.
Example:"boaty.mcboatface@sumup.com"
- expires_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- permissions []string required
User's permissions.
CloseAttributes - roles []string required
User's roles.
CloseAttributes - status string required
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
- user object
User information.
CloseAttributes- classic object
Classic identifiers of the user.
CloseAttributes- user_id integer required
-
- disabled_at string
Time when the user has been disabled. Applies only to virtual users (
virtual_user: true
). - 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"
- id string required
Identifier for the End-User (also called Subject).
Example:"44ca0f5b-813b-46e1-aee7-e6242010662e"
- mfa_on_login_enabled boolean required
True if the user has enabled MFA on login.
Example:true
- nickname string
User's perferred 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"
- virtual_user boolean required
True if the user is a virtual user (operator).
-
-
- total_count integer requiredExample:
3
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members
{
"items": [
{
"created_at": "2023-01-20T15:16:17Z",
"id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
"permissions": [
"members_read",
"members_write",
"create_moto_payments",
"full_transaction_history_view",
"refund_transactions",
"create_referral",
"developer_settings_write",
"developer_settings_read"
],
"roles": [
"role_admin",
"role_owner"
],
"status": "accepted",
"updated_at": "2023-02-20T15:16:17Z",
"user": {
"email": "example@sumup.com",
"id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
"mfa_on_login_enabled": true,
"virtual_user": false
}
}
],
"total_count": 3
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Body Parameters
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- email string required
Email address of the member to add.
- 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.
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- nickname string
Nickname of the member to add. Only used if
is_managed_user
is true. Used for display purposes only.Example:"Test User"
- password string
Password of the member to add. Only used if
is_managed_user
is true. - roles []string required
List of roles to assign to the new member.
CloseAttributes
Response 201
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
ID of the member.
Example:"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- invite object
Pending invitation for membership.
CloseInvite- email string required
Email address of the invited user.
Example:"boaty.mcboatface@sumup.com"
- expires_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- permissions []string required
User's permissions.
CloseAttributes - roles []string required
User's roles.
CloseAttributes - status string required
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
- user object
User information.
CloseAttributes- classic object
Classic identifiers of the user.
CloseAttributes- user_id integer required
-
- disabled_at string
Time when the user has been disabled. Applies only to virtual users (
virtual_user: true
). - 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"
- id string required
Identifier for the End-User (also called Subject).
Example:"44ca0f5b-813b-46e1-aee7-e6242010662e"
- mfa_on_login_enabled boolean required
True if the user has enabled MFA on login.
Example:true
- nickname string
User's perferred 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"
- virtual_user boolean required
True if the user is a virtual user (operator).
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members
{
"created_at": "2023-01-20T15:16:17Z",
"id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
"permissions": [
"members_read",
"members_write",
"create_moto_payments",
"full_transaction_history_view",
"refund_transactions",
"create_referral",
"developer_settings_write",
"developer_settings_read"
],
"roles": [
"role_admin",
"role_owner"
],
"status": "accepted",
"updated_at": "2023-02-20T15:16:17Z",
"user": {
"email": "example@sumup.com",
"id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
"mfa_on_login_enabled": true,
"virtual_user": false
}
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- member_id string requiredExample:
mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
Response 200
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
ID of the member.
Example:"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- invite object
Pending invitation for membership.
CloseInvite- email string required
Email address of the invited user.
Example:"boaty.mcboatface@sumup.com"
- expires_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- permissions []string required
User's permissions.
CloseAttributes - roles []string required
User's roles.
CloseAttributes - status string required
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
- user object
User information.
CloseAttributes- classic object
Classic identifiers of the user.
CloseAttributes- user_id integer required
-
- disabled_at string
Time when the user has been disabled. Applies only to virtual users (
virtual_user: true
). - 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"
- id string required
Identifier for the End-User (also called Subject).
Example:"44ca0f5b-813b-46e1-aee7-e6242010662e"
- mfa_on_login_enabled boolean required
True if the user has enabled MFA on login.
Example:true
- nickname string
User's perferred 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"
- virtual_user boolean required
True if the user is a virtual user (operator).
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id}
{
"created_at": "2023-01-20T15:16:17Z",
"id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
"permissions": [
"members_read",
"members_write",
"create_moto_payments",
"full_transaction_history_view",
"refund_transactions",
"create_referral",
"developer_settings_write",
"developer_settings_read"
],
"roles": [
"role_admin",
"role_owner"
],
"status": "accepted",
"updated_at": "2023-02-20T15:16:17Z",
"user": {
"email": "example@sumup.com",
"id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
"mfa_on_login_enabled": true,
"virtual_user": false
}
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- member_id string requiredExample:
mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
Body Parameters
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- roles []stringCloseAttributes
- user object
Allows you to update user data of managed users.
CloseAttributes- nickname string
User's perferred 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.
-
Response 200
- attributes object
Object attributes that modifiable only by SumUp applications.
CloseAttributesExample:{}
- created_at string requiredExample:
"2023-01-20T15:16:17Z"
- id string required
ID of the member.
Example:"mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- invite object
Pending invitation for membership.
CloseInvite- email string required
Email address of the invited user.
Example:"boaty.mcboatface@sumup.com"
- expires_at string requiredExample:
"2023-01-20T15:16:17Z"
-
- metadata object
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
CloseAttributesExample:{}
- permissions []string required
User's permissions.
CloseAttributes - roles []string required
User's roles.
CloseAttributes - status string required
- updated_at string requiredExample:
"2023-01-20T15:16:17Z"
- user object
User information.
CloseAttributes- classic object
Classic identifiers of the user.
CloseAttributes- user_id integer required
-
- disabled_at string
Time when the user has been disabled. Applies only to virtual users (
virtual_user: true
). - 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"
- id string required
Identifier for the End-User (also called Subject).
Example:"44ca0f5b-813b-46e1-aee7-e6242010662e"
- mfa_on_login_enabled boolean required
True if the user has enabled MFA on login.
Example:true
- nickname string
User's perferred 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"
- virtual_user boolean required
True if the user is a virtual user (operator).
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id}
{
"created_at": "2023-01-20T15:16:17Z",
"id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
"permissions": [
"members_read",
"members_write",
"create_moto_payments",
"full_transaction_history_view",
"refund_transactions",
"create_referral",
"developer_settings_write",
"developer_settings_read"
],
"roles": [
"role_admin",
"role_owner"
],
"status": "accepted",
"updated_at": "2023-02-20T15:16:17Z",
"user": {
"email": "example@sumup.com",
"id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
"mfa_on_login_enabled": true,
"virtual_user": false
}
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- member_id string requiredExample:
mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id}
Readers
Preview 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.
Attributes
- created_at string required
Reader creation timestamp.
Example:"2023-01-18T15:16:17Z"
- device object required
Information about the underlying physical device.
CloseAttributes- identifier string required
A unique identifier of the physical device (e.g. serial number).
Example:"U1DT3NA00-CN"
- model string requiredOptions:
solo
virtual-solo
Identifier of the model of the device.
Example:"solo"
-
- 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"
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- 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 ressource needs to get recreated
Example:"paired"
- updated_at string required
Reader last-modification timestamp.
Example:"2023-01-20T15:16:17Z"
{
"created_at": "2023-01-18T15:16:17Z",
"device": {
"identifier": "U1DT3NA00-CN",
"model": "solo"
},
"id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
"meta": {},
"name": "Frontdesk",
"status": "paired",
"updated_at": "2023-01-20T15:16:17Z"
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Response 200
- items []object requiredCloseAttributes
- created_at string required
Reader creation timestamp.
Example:"2023-01-18T15:16:17Z"
- device object required
Information about the underlying physical device.
CloseAttributes- identifier string required
A unique identifier of the physical device (e.g. serial number).
Example:"U1DT3NA00-CN"
- model string requiredOptions:
solo
virtual-solo
Identifier of the model of the device.
Example:"solo"
-
- 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"
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- 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 ressource needs to get recreated
Example:"paired"
- updated_at string required
Reader last-modification timestamp.
Example:"2023-01-20T15:16:17Z"
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers
{
"items": [
{
"created_at": "2023-01-18T15:16:17Z",
"device": {
"identifier": "U1DT3NA00-CN",
"model": "solo"
},
"id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
"meta": {},
"name": "Frontdesk",
"status": "paired",
"updated_at": "2023-01-20T15:16:17Z"
}
]
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
Body Parameters
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- name string
Custom human-readable, user-defined name for easier identification of the reader.
Example:"Frontdesk"
- 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"
Response 201
- created_at string required
Reader creation timestamp.
Example:"2023-01-18T15:16:17Z"
- device object required
Information about the underlying physical device.
CloseAttributes- identifier string required
A unique identifier of the physical device (e.g. serial number).
Example:"U1DT3NA00-CN"
- model string requiredOptions:
solo
virtual-solo
Identifier of the model of the device.
Example:"solo"
-
- 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"
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- 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 ressource needs to get recreated
Example:"paired"
- updated_at string required
Reader last-modification timestamp.
Example:"2023-01-20T15:16:17Z"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers
""
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- id string requiredExample:
rdr_3MSAFM23CK82VSTT4BN6RWSQ65
Response 200
- created_at string required
Reader creation timestamp.
Example:"2023-01-18T15:16:17Z"
- device object required
Information about the underlying physical device.
CloseAttributes- identifier string required
A unique identifier of the physical device (e.g. serial number).
Example:"U1DT3NA00-CN"
- model string requiredOptions:
solo
virtual-solo
Identifier of the model of the device.
Example:"solo"
-
- 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"
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- 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 ressource needs to get recreated
Example:"paired"
- updated_at string required
Reader last-modification timestamp.
Example:"2023-01-20T15:16:17Z"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}
{
"created_at": "2023-01-18T15:16:17Z",
"device": {
"identifier": "U1DT3NA00-CN",
"model": "solo"
},
"id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
"meta": {},
"name": "Frontdesk",
"status": "paired",
"updated_at": "2023-01-20T15:16:17Z"
}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- id string requiredExample:
rdr_3MSAFM23CK82VSTT4BN6RWSQ65
Body Parameters
- meta object
Set of user-defined key-value pairs attached to the object.
CloseAttributesExample:{}
- name string
Custom human-readable, user-defined name for easier identification of the reader.
Example:"Frontdesk"
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- id string requiredExample:
rdr_3MSAFM23CK82VSTT4BN6RWSQ65
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}
Create a Reader Checkout
Create 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.
readers.write
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- id string requiredExample:
rdr_3MSAFM23CK82VSTT4BN6RWSQ65
Body Parameters
- affiliate object
Affiliate metadata for the transaction. It is an optional field that allow for integrators to track the source of the transaction.
CloseAttributes- 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:"123456"
- 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 associoated with the transaction.
CloseAttributesExample:{}
-
- card_type stringOptions:
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.
CloseAttributes - total_amount object required
Amount of the transaction. 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.
CloseAttributes- 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
Total amount of the transaction. It must be a positive integer.
Example:1000
-
Response 201
- data objectCloseAttributes
- client_transaction_id string
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:"123e4567-e89b-12d3-a456-426614174000"
-
Response 400
- errors objectCloseAttributes
- detail stringExample:
"Bad Request"
-
Response 422
- errors objectCloseAttributes
Response 500
- errors objectCloseAttributes
- detail stringExample:
"Internal Server Error"
-
Response 502
- errors objectCloseAttributes
- detail stringExample:
"Bad Gateway"
-
Response 504
- errors objectCloseAttributes
- detail stringExample:
"Gateway Timeout"
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}/checkout
{
"data": {
"client_transaction_id": "123e4567-e89b-12d3-a456-426614174000"
}
}
Create a Reader Terminate action
Create a Terminate action for a Reader.
It 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.
readers.write
Path Parameters
- merchant_code string requiredExample:
MC0X0ABC
- id string requiredExample:
rdr_3MSAFM23CK82VSTT4BN6RWSQ65
Response 422
- errors objectCloseAttributes
Response 500
- errors objectCloseAttributes
- detail stringExample:
"Internal Server Error"
-
Response 502
- errors objectCloseAttributes
- detail stringExample:
"Bad Gateway"
-
Response 504
- errors objectCloseAttributes
- detail stringExample:
"Gateway Timeout"
-
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}/terminate
Receipts
The Receipts model obtains receipt-like details for specific transactions.
The Receipt object
Attributes
- acquirer_data objectCloseAttributes
- authorization_code string
- local_time string
- return_code string
- tid string
-
- emv_data objectCloseAttributes
- merchant_data object
Receipt merchant data
CloseAttributes- locale string
- merchant_profile objectCloseAttributes
- address objectCloseAttributes
- address_line1 string
- city string
- country string
- country_en_name string
- country_native_name string
- landline string
- post_code string
-
- business_name string
- email string
- merchant_code string
-
-
- transaction_data object
Transaction information.
CloseAttributes- amount string
Transaction amount.
- card objectCloseAttributes
- last_4_digits string
Card last 4 digits.
- type string
Card Scheme.
-
- currency string
Transaction currency.
- entry_mode string
Transaction entry mode.
- events []object
Events
CloseAttributes- amount number
Amount of the event.
- id integer
Unique ID of the transaction event.
- receipt_no string
- status string
Status of the transaction event.
- timestamp string
Date and time of the transaction event.
- transaction_id string
Unique ID of the transaction.
- type string
Type of the transaction event.
-
- installments_count integer
Number of installments.
- payment_type string
Transaction type.
- products []object
Products
CloseAttributes- description string
Product description.
- name string
Product name.
- price number
Product price.
- quantity integer
Product quantity.
- total_price number
Quantity x product price.
-
- receipt_no string
Receipt number
- status string
Transaction processing status.
- timestamp string
Time created at.
- tip_amount string
Tip amount (included in transaction amount).
- transaction_code string
Transaction code.
- vat_amount string
Transaction VAT amount.
- vat_rates []object
Vat rates.
CloseAttributes- gross number
Gross
- net number
Net
- rate number
Rate
- vat number
Vat
-
- verification_method string
Cardholder verification method.
-
{
"acquirer_data": {
"authorization_code": null,
"local_time": null,
"return_code": null,
"tid": null
},
"emv_data": {},
"merchant_data": {
"locale": null,
"merchant_profile": {
"address": {
"address_line1": null,
"city": null,
"country": null,
"country_en_name": null,
"country_native_name": null,
"landline": null,
"post_code": null
},
"business_name": null,
"email": null,
"merchant_code": null
}
},
"transaction_data": {
"amount": null,
"card": {
"last_4_digits": null,
"type": null
},
"currency": null,
"entry_mode": null,
"events": [
{
"amount": null,
"id": null,
"receipt_no": null,
"status": null,
"timestamp": null,
"transaction_id": null,
"type": null
}
],
"installments_count": null,
"payment_type": null,
"products": [
{
"description": null,
"name": null,
"price": null,
"quantity": null,
"total_price": null
}
],
"receipt_no": null,
"status": null,
"timestamp": null,
"tip_amount": null,
"transaction_code": null,
"vat_amount": null,
"vat_rates": [
{
"gross": null,
"net": null,
"rate": null,
"vat": null
}
],
"verification_method": null
}
}
Path Parameters
- id string required
Query Parameters
- mid string required
- tx_event_id integer
Response 200
- acquirer_data objectCloseAttributes
- authorization_code string
- local_time string
- return_code string
- tid string
-
- emv_data objectCloseAttributes
- merchant_data object
Receipt merchant data
CloseAttributes- locale string
- merchant_profile objectCloseAttributes
- address objectCloseAttributes
- address_line1 string
- city string
- country string
- country_en_name string
- country_native_name string
- landline string
- post_code string
-
- business_name string
- email string
- merchant_code string
-
-
- transaction_data object
Transaction information.
CloseAttributes- amount string
Transaction amount.
- card objectCloseAttributes
- last_4_digits string
Card last 4 digits.
- type string
Card Scheme.
-
- currency string
Transaction currency.
- entry_mode string
Transaction entry mode.
- events []object
Events
CloseAttributes- amount number
Amount of the event.
- id integer
Unique ID of the transaction event.
- receipt_no string
- status string
Status of the transaction event.
- timestamp string
Date and time of the transaction event.
- transaction_id string
Unique ID of the transaction.
- type string
Type of the transaction event.
-
- installments_count integer
Number of installments.
- payment_type string
Transaction type.
- products []object
Products
CloseAttributes- description string
Product description.
- name string
Product name.
- price number
Product price.
- quantity integer
Product quantity.
- total_price number
Quantity x product price.
-
- receipt_no string
Receipt number
- status string
Transaction processing status.
- timestamp string
Time created at.
- tip_amount string
Tip amount (included in transaction amount).
- transaction_code string
Transaction code.
- vat_amount string
Transaction VAT amount.
- vat_rates []object
Vat rates.
CloseAttributes- gross number
Gross
- net number
Net
- rate number
Rate
- vat number
Vat
-
- verification_method string
Cardholder verification method.
-
Response 400
- error_code string
Platform code for the error.
- message string
Short description of the error.
Response 401
- error_code string
Platform code for the error.
- message string
Short description of the error.
curl https://api.sumup.com/v1.1/receipts/{id}
{
"acquirer_data": {
"authorization_code": null,
"local_time": null,
"return_code": null,
"tid": null
},
"emv_data": {},
"merchant_data": {
"locale": null,
"merchant_profile": {
"address": {
"address_line1": null,
"city": null,
"country": null,
"country_en_name": null,
"country_native_name": null,
"landline": null,
"post_code": null
},
"business_name": null,
"email": null,
"merchant_code": null
}
},
"transaction_data": {
"amount": null,
"card": {
"last_4_digits": null,
"type": null
},
"currency": null,
"entry_mode": null,
"events": [
{
"amount": null,
"id": null,
"receipt_no": null,
"status": null,
"timestamp": null,
"transaction_id": null,
"type": null
}
],
"installments_count": null,
"payment_type": null,
"products": [
{
"description": null,
"name": null,
"price": null,
"quantity": null,
"total_price": null
}
],
"receipt_no": null,
"status": null,
"timestamp": null,
"tip_amount": null,
"transaction_code": null,
"vat_amount": null,
"vat_rates": [
{
"gross": null,
"net": null,
"rate": null,
"vat": null
}
],
"verification_method": null
}
}