Customers | SumUp Developer

Customers represent payers in your integration. Create a customer with your own customer_id to associate their personal details and saved payment instruments with your business records.

To save a card, create a checkout for that customer with purpose = SETUP_RECURRING_PAYMENT, then process it with the payer’s consent and mandate details. See the tokenization guide.

Use the Customers endpoints to create, retrieve, or update customer details and to list or deactivate saved payment instruments. For subsequent payments, process a new checkout with the saved instrument’s token and its associated customer_id.

Endpoints

The Customer object

Saved payer details identified by the customer_id supplied by your integration. A customer can have saved payment instruments for subsequent payments.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

1
{
2
  "customer_id": "831ff8d4cd5958ab5670",
3
  "personal_details": {
4
    "first_name": "John",
5
    "last_name": "Doe",
6
    "email": "user@example.com",
7
    "phone": "+491635559723",
8
    "birth_date": "1993-12-31",
9
    "tax_id": "423.378.593-47",
10
    "address": {
11
      "city": "Berlin",
12
      "country": "DE",
13
      "line_1": "Sample street",
14
      "line_2": "ap. 5",
15
      "postal_code": "10115",
16
      "state": "Berlin"
17
    }
18
  }
19
}

Customers

Create a customer

POST/v0.1/customers

Creates a customer using the customer_id you supply. Choose an identifier that maps to the payer in your own system and reuse it when retrieving the customer or associating checkouts and saved payment instruments with them.

Requires one of scopes:payment_instrumentscustomers.write

Body Parameters

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response

Returns the customer resource. See Customer object.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

1
curl https://api.sumup.com/v0.1/customers \
2
 -X POST \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "customer_id": "831ff8d4cd5958ab5670"
6
  }'

1
sumup customers create \
2
  --first-name "John" \
3
  --last-name "Doe" \
4
  --email "user@example.com" \
5
  --phone "+491635559723" \
6
  --tax-id "423.378.593-47" \
7
  --birth-date "1993-12-31" \
8
  --address-line-1 "Sample street" \
9
  --address-line-2 "ap. 5" \
10
  --address-city "Berlin" \
11
  --address-postal-code "10115" \
12
  --address-state "Berlin" \
13
  --address-country "DE"

1
import SumUp from "@sumup/sdk";
2

3
async function main() {
4
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });
5

6
  const result = await client.customers.create(
7
    {
8
      "customer_id": "831ff8d4cd5958ab5670"
9
    }
10
  );
11
  console.log(result);
12
}
13

14
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Customers.CreateAsync(
12
            new Customer
13
            {
14
                CustomerId = "831ff8d4cd5958ab5670",
15
            });
16

17
        Console.WriteLine(response.StatusCode);
18
    }
19
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class CreateCustomerSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.customers().create(
8
            com.sumup.sdk.models.Customer.builder()
9
                .customerId("831ff8d4cd5958ab5670")
10
                .build()
11
        );
12
    System.out.println(result);
13
  }
14
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.customers.create(
7
    customer_id="831ff8d4cd5958ab5670",
8
)
9
print(result)

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

3
$result = $sumup->customers->create([
4
  'customer_id' => '831ff8d4cd5958ab5670',
5
]);

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Customers.Create(context.TODO(), sumup.CustomersCreateParams{
13
    CustomerID: "831ff8d4cd5958ab5670",
14
  })
15
  if err != nil {
16
    panic(err.Error())
17
  }
18

19
  fmt.Printf("%+v\n", result)
20
}

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let body = sumup::resources::customers::CreateRequest {
7
        customer_id: "831ff8d4cd5958ab5670".to_string(),
8
        personal_details: None,
9
    };
10
    let response = client.customers().create(body).await.expect("create request failed");
11
    println!("{response:#?}");
12
}

1
{
2
  "customer_id": "831ff8d4cd5958ab5670",
3
  "personal_details": {
4
    "first_name": "John",
5
    "last_name": "Doe",
6
    "email": "user@example.com",
7
    "phone": "+491635559723",
8
    "birth_date": "1993-12-31",
9
    "tax_id": "423.378.593-47",
10
    "address": {
11
      "city": "Berlin",
12
      "country": "DE",
13
      "line_1": "Sample street",
14
      "line_2": "ap. 5",
15
      "postal_code": "10115",
16
      "state": "Berlin"
17
    }
18
  }
19
}

Content-Type: application/json

The request body is invalid.

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Content-Type: application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

A customer with the provided identifier already exists.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "error_code": "INVALID",
3
  "message": "Validation error",
4
  "param": "customer_id"
5
}

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "request_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "message": "Customer already exists",
3
  "error_code": "CUSTOMER_ALREADY_EXISTS"
4
}

Customers

Retrieve a customer

GET/v0.1/customers/{customer_id}

Retrieves a saved customer using the customer_id you supplied when creating the customer.

Requires one of scopes:payment_instrumentscustomers.read

Path Parameters

customer_idstringrequired
The customer_id you supplied when creating the customer.

Example: "831ff8d4cd5958ab5670"

Response

Returns the customer resource. See Customer object.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

1
curl https://api.sumup.com/v0.1/customers/{customer_id} \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
sumup customers get "831ff8d4cd5958ab5670"

1
import SumUp from "@sumup/sdk";
2

3
async function main() {
4
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });
5

6
  const result = await client.customers.get(
7
    "831ff8d4cd5958ab5670"
8
  );
9
  console.log(result);
10
}
11

12
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Customers.GetAsync(
12
            "example-id");
13

14
        Console.WriteLine(response.StatusCode);
15
    }
16
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class GetCustomerSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.customers().get(
8
            "831ff8d4cd5958ab5670"
9
        );
10
    System.out.println(result);
11
  }
12
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.customers.get(
7
    "831ff8d4cd5958ab5670",
8
)
9
print(result)

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

3
$result = $sumup->customers->get('831ff8d4cd5958ab5670');

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Customers.Get(context.TODO(), "831ff8d4cd5958ab5670")
13
  if err != nil {
14
    panic(err.Error())
15
  }
16

17
  fmt.Printf("%+v\n", result)
18
}

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .customers()
8
        .get("CUSTOMER_ID")
9
        .await
10
        .expect("get request failed");
11
    println!("{response:#?}");
12
}

1
{
2
  "customer_id": "831ff8d4cd5958ab5670",
3
  "personal_details": {
4
    "first_name": "John",
5
    "last_name": "Doe",
6
    "email": "user@example.com",
7
    "phone": "+491635559723",
8
    "birth_date": "1993-12-31",
9
    "tax_id": "423.378.593-47",
10
    "address": {
11
      "city": "Berlin",
12
      "country": "DE",
13
      "line_1": "Sample street",
14
      "line_2": "ap. 5",
15
      "postal_code": "10115",
16
      "state": "Berlin"
17
    }
18
  }
19
}

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Content-Type: application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "request_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

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.

Requires one of scopes:payment_instrumentscustomers.write

Path Parameters

customer_idstringrequired
The customer_id you supplied when creating the customer.

Example: "831ff8d4cd5958ab5670"

Body Parameters

personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response

Returns the customer resource. See Customer object.

customer_idstringrequired
Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.

Example: "831ff8d4cd5958ab5670"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  Identification number used for tax purposes, such as a CPF in Brazil.
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

1
curl https://api.sumup.com/v0.1/customers/{customer_id} \
2
 -X PUT \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{}'

1
sumup customers update "831ff8d4cd5958ab5670" \
2
  --first-name "John" \
3
  --last-name "Doe" \
4
  --email "user@example.com" \
5
  --phone "+491635559723" \
6
  --tax-id "423.378.593-47" \
7
  --birth-date "1993-12-31" \
8
  --address-line-1 "Sample street" \
9
  --address-line-2 "ap. 5" \
10
  --address-city "Berlin" \
11
  --address-postal-code "10115" \
12
  --address-state "Berlin" \
13
  --address-country "DE"

1
import SumUp from "@sumup/sdk";
2

3
async function main() {
4
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });
5

6
  const result = await client.customers.update(
7
    "831ff8d4cd5958ab5670",
8
    {}
9
  );
10
  console.log(result);
11
}
12

13
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Customers.UpdateAsync(
12
            "example-id",
13
            new CustomersUpdateRequest { });
14

15
        Console.WriteLine(response.StatusCode);
16
    }
17
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class UpdateCustomerSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.customers().update(
8
            "831ff8d4cd5958ab5670",
9
            com.sumup.sdk.models.UpdateCustomerRequest.builder()
10
                .build()
11
        );
12
    System.out.println(result);
13
  }
14
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.customers.update(
7
    "831ff8d4cd5958ab5670",
8
)
9
print(result)

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

3
$result = $sumup->customers->update('831ff8d4cd5958ab5670', [
4

5
]);

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Customers.Update(context.TODO(), "831ff8d4cd5958ab5670", sumup.CustomersUpdateParams{})
13
  if err != nil {
14
    panic(err.Error())
15
  }
16

17
  fmt.Printf("%+v\n", result)
18
}

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let body = sumup::resources::customers::UpdateRequest {
7
        ..Default::default()
8
    };
9
    let response = client
10
        .customers()
11
        .update("CUSTOMER_ID", body)
12
        .await
13
        .expect("update request failed");
14
    println!("{response:#?}");
15
}

1
{
2
  "customer_id": "831ff8d4cd5958ab5670",
3
  "personal_details": {
4
    "first_name": "John",
5
    "last_name": "Doe",
6
    "email": "user@example.com",
7
    "phone": "+491635559723",
8
    "birth_date": "1993-12-31",
9
    "tax_id": "423.378.593-47",
10
    "address": {
11
      "city": "Berlin",
12
      "country": "DE",
13
      "line_1": "Sample street",
14
      "line_2": "ap. 5",
15
      "postal_code": "10115",
16
      "state": "Berlin"
17
    }
18
  }
19
}

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Content-Type: application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "request_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

Customers

List payment instruments

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

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

Requires one of scopes:payment_instrumentscustomers.read

Path Parameters

customer_idstringrequired
The customer_id you supplied when creating the customer.

Example: "831ff8d4cd5958ab5670"

Response

Returns the list of saved payment instruments for the customer.

[]PaymentInstrumentResponse

Show attributes

tokenstringRead only
Token identifying the customer's saved payment card. Pass it as token, together with the associated customer_id and payment_type = card, when processing a checkout with this instrument.

Example: "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"
activebooleandefault: 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.
typestring
Options: card
Type of the payment instrument.

Example: "card"
cardobject
Details of the payment card.
Show attributes
Close
Attributes
- last_4_digitsstringmin length: 4, max length: 4, Read only
  Last 4 digits of the payment card number.
  
  Example: "3456"
- typeCard Type
  Options: ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN
  Issuing card network of the payment card used for the transaction.
  
  Example: "VISA"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
  
  Example: "recurrent"
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Short unique identifier for the merchant for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
created_atstringformat: date-time
The timestamp of when the payment instrument was created.

Example: "2021-03-30T10:06:07.000+00:00"

1
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
sumup customers payment-instruments list "831ff8d4cd5958ab5670"

1
import SumUp from "@sumup/sdk";
2

3
async function main() {
4
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });
5

6
  const result = await client.customers.listPaymentInstruments(
7
    "831ff8d4cd5958ab5670"
8
  );
9
  console.log(result);
10
}
11

12
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Customers.ListPaymentInstrumentsAsync(
12
            "example-id");
13

14
        Console.WriteLine(response.StatusCode);
15
    }
16
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class ListPaymentInstrumentsSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.customers().listPaymentInstruments(
8
            "831ff8d4cd5958ab5670"
9
        );
10
    System.out.println(result);
11
  }
12
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.customers.list_payment_instruments(
7
    "831ff8d4cd5958ab5670",
8
)
9
print(result)

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

3
$result = $sumup->customers->listPaymentInstruments('831ff8d4cd5958ab5670');

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Customers.ListPaymentInstruments(context.TODO(), "831ff8d4cd5958ab5670")
13
  if err != nil {
14
    panic(err.Error())
15
  }
16

17
  fmt.Printf("%+v\n", result)
18
}

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .customers()
8
        .list_payment_instruments("CUSTOMER_ID")
9
        .await
10
        .expect("list_payment_instruments request failed");
11
    println!("{response:#?}");
12
}

1
[
2
  {
3
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
4
    "active": true,
5
    "type": "card",
6
    "mandate": {
7
      "type": "recurrent",
8
      "status": "active",
9
      "merchant_code": "MH4H92C7"
10
    },
11
    "card": {
12
      "last_4_digits": "0001",
13
      "type": "VISA"
14
    },
15
    "created_at": "2021-03-30T10:06:07.000+00:00"
16
  }
17
]

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Content-Type: application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "request_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

Customers

Deactivate a payment instrument

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

Deactivates an identified card payment instrument resource for a customer.

Requires one of scopes:payment_instrumentscustomers.write

Path Parameters

customer_idstringrequired
The customer_id you supplied when creating the customer.

Example: "831ff8d4cd5958ab5670"
tokenstringrequired
Unique token identifying the card saved as a payment instrument resource.

Example: "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"

Response

Returns empty response.

1
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token} \
2
 -X DELETE \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
sumup customers payment-instruments deactivate "831ff8d4cd5958ab5670" "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"

1
import SumUp from "@sumup/sdk";
2

3
async function main() {
4
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });
5

6
  const result = await client.customers.deactivatePaymentInstrument(
7
    "831ff8d4cd5958ab5670",
8
    "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"
9
  );
10
  console.log(result);
11
}
12

13
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Customers.DeactivatePaymentInstrumentAsync(
12
            "example-id",
13
            "example");
14

15
        Console.WriteLine(response.StatusCode);
16
    }
17
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class DeactivatePaymentInstrumentSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    client.customers().deactivatePaymentInstrument(
8
            "831ff8d4cd5958ab5670",
9
            "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"
10
        );
11
  }
12
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
client.customers.deactivate_payment_instrument(
7
    "831ff8d4cd5958ab5670",
8
    "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
9
)

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

3
$result = $sumup->customers->deactivatePaymentInstrument('831ff8d4cd5958ab5670', 'bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3');

1
package main
2

3
import (
4
  "context"
5

6
  "github.com/sumup/sumup-go"
7
)
8

9
func main() {
10
  client := sumup.NewClient()
11
  if err := client.Customers.DeactivatePaymentInstrument(context.TODO(), "831ff8d4cd5958ab5670", "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3"); err != nil {
12
    panic(err.Error())
13
  }
14
}

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .customers()
8
        .deactivate_payment_instrument("CUSTOMER_ID", "PAYMENT_INSTRUMENT_TOKEN")
9
        .await
10
        .expect("deactivate_payment_instrument request failed");
11
    println!("{response:#?}");
12
}

Content-Type: application/json

The request is invalid.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

Content-Type: application/json

The request is authenticated but not permitted for this operation.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "error_code": "INVALID_REQUEST",
3
  "message": "bad request"
4
}

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "request_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}