Skip to content
SumUp Developer

Customers

SumUp API reference and code samples.

Customers

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

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

The Customer object

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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

Create a customer

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

Required scopes: payment_instruments

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const 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"
    }
  }
}
Customers

Retrieve a customer

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const 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"
    }
  }
}
Customers

Update a customer

Updates an identified saved customer resource's personal details.

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Body Parameters

  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

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

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      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 object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

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


const 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"
    }
  }
}
Customers

List payment instruments

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Response 200

[]object
 Show attributes
 Close
Attributes
  • token string read only

    Unique token identifying the saved payment card for a customer.

  • active boolean default: trueread 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: 4max length: 4read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type string

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

  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • created_at string 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"
  }
]
Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

  • token string required

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

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;