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.
openapi: 3.0.1
info:
title: SumUp REST Checkouts Customers API
version: 1.0.0
description: 'SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status).
You can experiment and work on your integration in a sandbox that doesn''t affect your regular data and doesn''t process real transactions. To create a sandbox merchant account visit the [dashboard](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication).'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.sumup.com
description: Production server
tags:
- name: Customers
description: '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.'
x-core-objects:
- $ref: '#/components/schemas/Customer'
paths:
/v0.1/customers:
post:
operationId: CreateCustomer
summary: Create a customer
description: Creates a new saved customer resource which you can later manipulate and save payment instruments to.
requestBody:
description: Details of the customer.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
responses:
'201':
description: Returns the customer resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
description: The request body is invalid.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorExtended'
- type: object
required:
- instance
- error_code
- error_message
properties:
instance:
type: string
error_code:
type: string
error_message:
type: string
examples:
Missing_Customer_ID:
description: The required customer identifier is missing.
value:
error_code: INVALID
message: Validation error
param: customer_id
'401':
description: The request is not authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
examples:
Problem_Details:
description: Unauthorized response returned by API gateway.
value:
detail: Unauthorized.
status: 401
title: Unauthorized
trace_id: 3c77294349d3b5647ea2d990f0d8f017
type: https://developer.sumup.com/problem/unauthorized
'403':
description: The request is authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
examples:
Forbidden:
description: You do not have required scopes for making this request.
value:
error_message: request_not_allowed
error_code: FORBIDDEN
status_code: '403'
'409':
description: A customer with the provided identifier already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Existing_Customer:
description: A resource with the specified identifier already exists on the server.
value:
message: Customer already exists
error_code: CUSTOMER_ALREADY_EXISTS
security:
- apiKey: []
- oauth2:
- payment_instruments
tags:
- Customers
x-codegen:
method_name: create
x-scopes:
- payment_instruments
/v0.1/customers/{customer_id}:
parameters:
- name: customer_id
in: path
description: Unique ID of the saved customer resource.
required: true
schema:
type: string
get:
operationId: GetCustomer
summary: Retrieve a customer
description: Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.
responses:
'200':
description: Returns the customer resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
description: The request is not authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
examples:
Problem_Details:
description: Unauthorized response returned by API gateway.
value:
detail: Unauthorized.
status: 401
title: Unauthorized
trace_id: 3c77294349d3b5647ea2d990f0d8f017
type: https://developer.sumup.com/problem/unauthorized
'403':
description: The request is authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
examples:
Forbidden:
description: You do not have required scopes for making this request.
value:
error_message: request_not_allowed
error_code: FORBIDDEN
status_code: '403'
'404':
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Not_Found:
description: The identified resource is not found on the server.
value:
error_code: NOT_FOUND
message: Resource not found
security:
- apiKey: []
- oauth2:
- payment_instruments
tags:
- Customers
x-codegen:
method_name: get
x-scopes:
- payment_instruments
put:
operationId: UpdateCustomer
summary: Update a customer
description: '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.'
requestBody:
description: Customer fields to update.
required: true
content:
application/json:
schema:
type: object
properties:
personal_details:
$ref: '#/components/schemas/PersonalDetails'
responses:
'200':
description: Returns the customer resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
description: The request is not authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
examples:
Problem_Details:
description: Unauthorized response returned by API gateway.
value:
detail: Unauthorized.
status: 401
title: Unauthorized
trace_id: 3c77294349d3b5647ea2d990f0d8f017
type: https://developer.sumup.com/problem/unauthorized
'403':
description: The request is authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
examples:
Forbidden:
description: You do not have required scopes for making this request.
value:
error_message: request_not_allowed
error_code: FORBIDDEN
status_code: '403'
'404':
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Not_Found:
description: The identified resource is not found on the server.
value:
error_code: NOT_FOUND
message: Resource not found
security:
- apiKey: []
- oauth2:
- payment_instruments
tags:
- Customers
x-codegen:
method_name: update
x-scopes:
- payment_instruments
/v0.1/customers/{customer_id}/payment-instruments:
parameters:
- name: customer_id
in: path
description: Unique ID of the saved customer resource.
required: true
schema:
type: string
get:
operationId: ListPaymentInstruments
summary: List payment instruments
description: Lists all payment instrument resources that are saved for an identified customer.
responses:
'200':
description: Returns the list of saved payment instruments for the customer.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PaymentInstrumentResponse'
'401':
description: The request is not authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
examples:
Problem_Details:
description: Unauthorized response returned by API gateway.
value:
detail: Unauthorized.
status: 401
title: Unauthorized
trace_id: 3c77294349d3b5647ea2d990f0d8f017
type: https://developer.sumup.com/problem/unauthorized
'403':
description: The request is authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
examples:
Forbidden:
description: You do not have required scopes for making this request.
value:
error_message: request_not_allowed
error_code: FORBIDDEN
status_code: '403'
'404':
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Not_Found:
description: The identified resource is not found on the server.
value:
error_code: NOT_FOUND
message: Resource not found
security:
- apiKey: []
- oauth2:
- payment_instruments
tags:
- Customers
x-codegen:
method_name: list_payment_instruments
x-scopes:
- payment_instruments
/v0.1/customers/{customer_id}/payment-instruments/{token}:
parameters:
- name: customer_id
in: path
description: Unique ID of the saved customer resource.
required: true
schema:
type: string
- name: token
in: path
description: Unique token identifying the card saved as a payment instrument resource.
required: true
schema:
type: string
delete:
operationId: DeactivatePaymentInstrument
summary: Deactivate a payment instrument
description: Deactivates an identified card payment instrument resource for a customer.
responses:
'204':
description: Returns an empty response body when the operation succeeds.
'400':
description: The request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Invalid_Request:
description: The request cannot be processed.
value:
error_code: INVALID_REQUEST
message: bad request
'401':
description: The request is not authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
examples:
Problem_Details:
description: Unauthorized response returned by API gateway.
value:
detail: Unauthorized.
status: 401
title: Unauthorized
trace_id: 3c77294349d3b5647ea2d990f0d8f017
type: https://developer.sumup.com/problem/unauthorized
'403':
description: The request is authenticated but not permitted for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbidden'
examples:
Forbidden:
description: You do not have required scopes for making this request.
value:
error_message: request_not_allowed
error_code: FORBIDDEN
status_code: '403'
'404':
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Not_Found:
description: The identified resource is not found on the server.
value:
error_code: NOT_FOUND
message: Resource not found
security:
- apiKey: []
- oauth2:
- payment_instruments
tags:
- Customers
x-codegen:
method_name: deactivate_payment_instrument
x-scopes:
- payment_instruments
components:
schemas:
ErrorExtended:
description: Error payload with the invalid parameter reference.
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
param:
description: Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, `card.name` refers to the `name` parameter embedded in the `card` object.
type: string
title: Error Extended
CardType:
description: Issuing card network of the payment card used for the transaction.
type: string
enum:
- ALELO
- AMEX
- CONECS
- CUP
- DINERS
- DISCOVER
- EFTPOS
- ELO
- ELV
- GIROCARD
- HIPERCARD
- INTERAC
- JCB
- MAESTRO
- MASTERCARD
- PLUXEE
- SWILE
- TICKET
- VISA
- VISA_ELECTRON
- VISA_VPAY
- VPAY
- VR
- UNKNOWN
title: Card Type
Customer:
description: Saved customer details.
type: object
properties:
customer_id:
description: Unique ID of the customer.
type: string
example: 831ff8d4cd5958ab5670
personal_details:
$ref: '#/components/schemas/PersonalDetails'
required:
- customer_id
title: Customer
AddressLegacy:
description: Profile's personal address information.
type: object
properties:
city:
description: City name from the address.
type: string
example: Berlin
country:
description: Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
type: string
example: DE
line_1:
description: First line of the address with details of the street name and number.
type: string
example: Sample street
line_2:
description: Second line of the address with details of the building, unit, apartment, and floor numbers.
type: string
example: ap. 5
postal_code:
description: Postal code from the address.
type: string
example: '10115'
state:
description: State name or abbreviation from the address.
type: string
example: Berlin
title: Address Legacy
MandateResponse:
description: Details of the mandate linked to the saved payment instrument.
type: object
properties:
type:
description: Type of mandate stored for the checkout or payment instrument.
type: string
status:
description: Current lifecycle status of the mandate.
type: string
example: active
enum:
- active
- inactive
merchant_code:
description: Merchant account for which the mandate is valid.
type: string
example: MH4H92C7
example:
type: recurrent
status: active
merchant_code: MH4H92C7
title: Mandate Response
ErrorForbidden:
description: Error message for forbidden requests.
type: object
properties:
error_message:
description: Short description of the error.
type: string
example: request_not_allowed
error_code:
description: Platform code for the error.
type: string
example: FORBIDDEN
status_code:
description: HTTP status code for the error.
type: string
example: '403'
title: Error Forbidden
Problem:
description: 'A RFC 9457 problem details object.
Additional properties specific to the problem type may be present.'
type: object
properties:
type:
description: A URI reference that identifies the problem type.
type: string
format: uri
example: https://developer.sumup.com/problem/not-found
title:
description: A short, human-readable summary of the problem type.
type: string
example: Requested resource couldn't be found.
status:
description: The HTTP status code generated by the origin server for this occurrence of the problem.
type: integer
example: 404
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
example: The requested resource doesn't exist or does not belong to you.
instance:
description: A URI reference that identifies the specific occurrence of the problem.
type: string
format: uri
additionalProperties: true
required:
- type
title: Problem
Error:
description: Error message structure.
type: object
properties:
message:
description: Short description of the error.
type: string
example: Resource not found
error_code:
description: Platform code for the error.
type: string
example: NOT_FOUND
title: Error
PaymentInstrumentResponse:
description: Payment Instrument Response
type: object
properties:
token:
description: Unique token identifying the saved payment card for a customer.
type: string
readOnly: true
active:
description: Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.
type: boolean
default: true
readOnly: true
type:
description: Type of the payment instrument.
type: string
enum:
- card
card:
description: Details of the payment card.
type: object
properties:
last_4_digits:
description: Last 4 digits of the payment card number.
type: string
example: '3456'
maxLength: 4
minLength: 4
readOnly: true
type:
$ref: '#/components/schemas/CardType'
mandate:
$ref: '#/components/schemas/MandateResponse'
created_at:
description: Creation date of payment instrument. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.
type: string
format: date-time
example:
token: bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3
active: true
type: card
mandate:
type: recurrent
status: active
merchant_code: MH4H92C7
card:
last_4_digits: '0001'
type: VISA
created_at: 2021-03-30 10:06:07+00:00
title: Payment Instrument Response
PersonalDetails:
description: Personal details for the customer.
type: object
properties:
first_name:
description: First name of the customer.
type: string
example: John
last_name:
description: Last name of the customer.
type: string
example: Doe
email:
description: Email address of the customer.
type: string
example: user@example.com
phone:
description: Phone number of the customer.
type: string
example: '+491635559723'
birth_date:
description: Date of birth of the customer.
type: string
format: date
example: 1993-12-31
tax_id:
description: An identification number user for tax purposes (e.g. CPF)
type: string
example: 423.378.593-47
maxLength: 255
address:
$ref: '#/components/schemas/AddressLegacy'
title: Personal Details
securitySchemes:
apiKey:
description: API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys)
type: http
scheme: Bearer
oauth2:
type: oauth2
description: 'SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users.
To integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications).
To maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.'
flows:
authorizationCode:
authorizationUrl: https://api.sumup.com/authorize
tokenUrl: https://api.sumup.com/token
refreshUrl: https://api.sumup.com/token
scopes:
payments: Make payments by creating and processing checkouts.
transactions.history: View transactions and transaction history.
user.profile_readonly: View user profile details.
user.profile: View and manage your user profile.
user.app-settings: View and manage the SumUp mobile application settings.
payment_instruments: Manage customers and their payment instruments.
user.payout-settings: View and manage your payout settings.
user.subaccounts: View and manage the user profile details of your employees.
clientCredentials:
tokenUrl: https://api.sumup.com/token
scopes:
payments: Make payments by creating and processing checkouts.
transactions.history: View transactions and transaction history.
user.profile_readonly: View user profile details.
user.profile: View and manage your user profile.
user.app-settings: View and manage the SumUp mobile application settings.
payment_instruments: Manage customers and their payment instruments.
user.payout-settings: View and manage your payout settings.
user.subaccounts: View and manage the user profile details of your employee.