Customers | SumUp Developer

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.

Endpoints

The Customer object

Saved customer details.

customer_idstringrequired
Unique identifier of the customer.

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.
  
  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 new saved customer resource which you can later manipulate and save payment instruments to.

Requires one of scopes:payment_instrumentscustomers.write

Body Parameters

customer_idstringrequired
Unique identifier of the customer.

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.
  
  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
Unique identifier of the customer.

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.
  
  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.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

7
public static class Program
8
{
9
    public static async Task Main()
10
    {
11
        using var client = new SumUpClient();
12
        var response = await client.Customers.CreateAsync(
13
            JsonSerializer.Deserialize<Customer>(@"{""customer_id"":""831ff8d4cd5958ab5670""}")!);
14

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

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 = serde_json::from_value(
7
            serde_json::json!({ "customer_id" : "831ff8d4cd5958ab5670" }),
8
        )
9
        .expect("build request body");
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 an identified saved customer resource through the unique customer_id parameter, generated upon customer creation.

Requires one of scopes:payment_instrumentscustomers.read

Path Parameters

customer_idstringrequired
Unique identifier of the saved customer resource.

Example: "831ff8d4cd5958ab5670"

Response

Returns the customer resource. See Customer object.

customer_idstringrequired
Unique identifier of the customer.

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.
  
  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.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

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

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

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
            "example"
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
Unique identifier of the saved customer resource.

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.
  
  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
Unique identifier of the customer.

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.
  
  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.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

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

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

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
            "example",
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 = serde_json::from_value(serde_json::json!({}))
7
        .expect("build request body");
8
    let response = client
9
        .customers()
10
        .update("CUSTOMER_ID", body)
11
        .await
12
        .expect("update request failed");
13
    println!("{response:#?}");
14
}

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
Unique identifier of the saved customer resource.

Example: "831ff8d4cd5958ab5670"

Response

Returns the list of saved payment instruments for the customer.

[]PaymentInstrumentResponse

Show attributes

tokenstringRead only
Unique token identifying the saved payment card for a customer.

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.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

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

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

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
            "example"
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
Unique identifier of the saved customer resource.

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.Text.Json;
4
using System.Threading.Tasks;
5
using SumUp;
6

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

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

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
            "example",
9
            "example"
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
}