List payment instruments

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

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

OAuth scopes: Requires one of: payment_instruments, customers.read.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes payment_instrumentscustomers.read

Authorization guide

Path parameters

customer_idstringrequired
The customer_id you supplied when creating the customer.

Example: "831ff8d4cd5958ab5670"

Responses

200application/json

Returns the list of saved payment instruments for the customer.

tokenstring
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"
activeboolean
default: true
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 2 properties
- last_4_digitsstring
  minLength: 4maxLength: 4
  Last 4 digits of the payment card number.
  
  Example: "3456"
- typestring
  Options:"ALELO""AMEX""BANCOMAT""CONECS""CUP""DINERS""DISCOVER""EFTPOS""ELO""ELV""GIROCARD""HIPERCARD""INTERAC""JCB""MAESTRO""MASTERCARD""PLUXEE""SUMUP""SWILE""TICKET""VISA""VISA_ELECTRON""VISA_VPAY""VPAY""VR""UNKNOWN"
  Issuing card network of the payment card used for the transaction.
  
  Example: "VISA"
mandateobject
Details of the mandate linked to the saved payment instrument.

Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
Show 3 properties
- typestring
  Type of mandate stored for the checkout or payment instrument.
  
  Example: "recurrent"
- statusstring
  Options:"active""inactive"
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Short unique identifier for the merchant for which the mandate is valid.
  
  Example: "MH4H92C7"
created_atstring
format: date-time
The timestamp of when the payment instrument was created.

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

401application/json

The request is not authorized.

typestringrequired
format: 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."
instancestring
format: 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"

403application/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"

404application/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"

GET

Code sample

curl --request GET \
  --url https://api.sumup.com/v0.1/customers/831ff8d4cd5958ab5670/payment-instruments \
  --header 'Authorization: Bearer <token>'

import SumUp from "@sumup/sdk";

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

  const result = await client.customers.listPaymentInstruments(
    "831ff8d4cd5958ab5670"
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Customers.ListPaymentInstrumentsAsync(
            "example-id");

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.customers().listPaymentInstruments(
            "831ff8d4cd5958ab5670"
        );
    System.out.println(result);
  }
}

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

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

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

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Customers.ListPaymentInstruments(context.TODO(), "831ff8d4cd5958ab5670")
	if err != nil {
		panic(err.Error())
	}

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

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let response = client
        .customers()
        .list_payment_instruments("CUSTOMER_ID")
        .await
        .expect("list_payment_instruments request failed");
    println!("{response:#?}");
}

Response example

[
  {
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "active": true,
    "type": "card",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MH4H92C7"
    },
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00"
  }
]

{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}

{
  "error_message": "request_not_allowed",
  "error_code": "FORBIDDEN",
  "status_code": "403"
}

{
  "error_code": "NOT_FOUND",
  "message": "Resource not found"
}