Skip to content
SumUp Developer

Customers

SumUp API reference and code samples.

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

Saved customer details.

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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

Create a customer

POST /v0.1/customers

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

Required scopes: payment_instruments

Body Parameters

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Response

Returns the customer resource. See Customer object .

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const client = new SumUp();


const result = await client.customers.create({
  customer_id: "831ff8d4cd5958ab5670",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.CreateAsync(
    new Customer
    {
        CustomerId = "831ff8d4cd5958ab5670",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().createCustomer(
  Customer.builder()
    .customerId("831ff8d4cd5958ab5670")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.create(CreateCustomerBody(
  customer_id="831ff8d4cd5958ab5670",
))
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->create([
  'customer_id' => '831ff8d4cd5958ab5670',
]);
client := sumup.NewClient()


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


let client = Client::default();


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

Content-Type: application/json

The request body is invalid.
Error 400
{
  "instance": "32a44c6c-85d3-49e8-86bf-a5bba98c4621",
  "error_code": "INVALID",
  "error_message": "customer_id"
}
Customers

Retrieve a customer

GET /v0.1/customers/{customer_id}

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Response

Returns the customer resource. See Customer object .

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const client = new SumUp();


const result = await client.customers.get("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.GetAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().getCustomer(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.get("customer_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->get('customer_id');
client := sumup.NewClient()


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


let client = Client::default();


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

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Customers

Update a customer

PUT /v0.1/customers/{customer_id}

Updates an identified saved customer resource's personal details.

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Body Parameters

  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Response

Returns the customer resource. See Customer object .

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

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

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const client = new SumUp();


const result = await client.customers.update("customer_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.UpdateAsync(
    "customer_id",
    new UpdateCustomerBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().updateCustomer(
  "customer_id",
  UpdateCustomerBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.update("customer_id", UpdateCustomerBody(


))
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->update('customer_id', [


]);
client := sumup.NewClient()


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


})
use sumup::Client;


let client = Client::default();


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

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Customers

List payment instruments

GET /v0.1/customers/{customer_id}/payment-instruments

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Response

Returns the list of saved payment instruments for the customer.

[]PaymentInstrumentResponse
 Show attributes
 Close
Payment Instrument Response
  • token string Read only

    Unique token identifying the saved payment card for a customer.

  • active boolean default: true, Read only

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

  • type string
    Options:  card

    Type of the payment instrument.

  • card object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits string min length: 4, max length: 4, Read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type Card Type
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

  • mandate Mandate Response

    Created mandate

     Show attributes
     Close
    Mandate Response
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • created_at string format: date-time

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

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


const client = new SumUp();


const result = await client.customers.listPaymentInstruments("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.ListPaymentInstrumentsAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().listPaymentInstruments(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.list_payment_instruments("customer_id")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->listPaymentInstruments('customer_id');
client := sumup.NewClient()


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


let client = Client::default();


let result = client.customers().list_payment_instruments("customer_id").await;
List payment instruments response
[
  {
    "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-30T10:06:07.000+00:00"
  }
]

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Customers

Deactivate a payment instrument

DELETE /v0.1/customers/{customer_id}/payment-instruments/{token}

Deactivates an identified card payment instrument resource for a customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

  • token string required

    Unique token identifying the card saved as a payment instrument resource.

Response

Returns empty response.

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


const client = new SumUp();


const result = await client.customers.deactivatePaymentInstrument("customer_id", "token");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.DeactivatePaymentInstrumentAsync(
    "customer_id",
    "token"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().deactivatePaymentInstrument(
  "customer_id",
  "token"
);
from sumup import Sumup


client = Sumup()


result = client.customers.deactivate_payment_instrument("customer_id", "token")
$sumup = new \SumUp\SumUp();


$result = $sumup->customers->deactivatePaymentInstrument('customer_id', 'token');
client := sumup.NewClient()


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


let client = Client::default();


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

Content-Type: application/json

The request is invalid.

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.
Error 400
{
  "error_code": "INVALID_REQUEST",
  "message": "bad request"
}