Create debit card
curl --request POST \
--url https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"nickname": "<string>",
"shippingAddress": {
"address1": "<string>",
"address2": "<string>",
"address3": "<string>",
"city": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards"
payload = {
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"nickname": "<string>",
"shippingAddress": {
"address1": "<string>",
"address2": "<string>",
"address3": "<string>",
"city": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
bankAccountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
nickname: '<string>',
shippingAddress: {
address1: '<string>',
address2: '<string>',
address3: '<string>',
city: '<string>',
postalCode: '<string>',
state: '<string>'
},
userId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'bankAccountId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'reference' => '<string>',
'nickname' => '<string>',
'shippingAddress' => [
'address1' => '<string>',
'address2' => '<string>',
'address3' => '<string>',
'city' => '<string>',
'postalCode' => '<string>',
'state' => '<string>'
],
'userId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards"
payload := strings.NewReader("{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"cardBrand": "UNKNOWN",
"cardStatus": "PENDING_ACTIVATION",
"cardType": "DIGITAL",
"cardholderName": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"expirationDate": "<string>",
"lastFourDigits": "<string>",
"reference": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "<string>",
"nickname": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}Debit Cards
Create debit card
Token types: APP, USER | Required scopes: debit_card:issue:org
POST
/
embedded-banking
/
v1
/
debit-cards
Create debit card
curl --request POST \
--url https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"nickname": "<string>",
"shippingAddress": {
"address1": "<string>",
"address2": "<string>",
"address3": "<string>",
"city": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards"
payload = {
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"nickname": "<string>",
"shippingAddress": {
"address1": "<string>",
"address2": "<string>",
"address3": "<string>",
"city": "<string>",
"postalCode": "<string>",
"state": "<string>"
},
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
bankAccountId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
nickname: '<string>',
shippingAddress: {
address1: '<string>',
address2: '<string>',
address3: '<string>',
city: '<string>',
postalCode: '<string>',
state: '<string>'
},
userId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'bankAccountId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'reference' => '<string>',
'nickname' => '<string>',
'shippingAddress' => [
'address1' => '<string>',
'address2' => '<string>',
'address3' => '<string>',
'city' => '<string>',
'postalCode' => '<string>',
'state' => '<string>'
],
'userId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards"
payload := strings.NewReader("{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.tesouro.com/embedded-banking/v1/debit-cards")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"bankAccountId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"reference\": \"<string>\",\n \"nickname\": \"<string>\",\n \"shippingAddress\": {\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"address3\": \"<string>\",\n \"city\": \"<string>\",\n \"postalCode\": \"<string>\",\n \"state\": \"<string>\"\n },\n \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bankAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"cardBrand": "UNKNOWN",
"cardStatus": "PENDING_ACTIVATION",
"cardType": "DIGITAL",
"cardholderName": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"expirationDate": "<string>",
"lastFourDigits": "<string>",
"reference": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "<string>",
"nickname": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}{
"detail": "<string>",
"errorCode": "<string>",
"instance": "<string>",
"status": 123,
"title": "<string>",
"type": "<string>"
}This feature is in Beta and not ready for production integration.
Authorizations
APPTokenUSERToken
Application (M2M) OAuth2 access token (client credentials).
Body
application/jsonapplication/*+json
Request to issue a debit card against a funding bank account. The debit card is provisioned
through TSYS and linked to the caller's bank account (the DDA) resolved from Guid CreateDebitCardRequest.BankAccountId.
Field- and cross-field validation (formats, lengths, card-type/shipping-address rules) is owned by
CreateDebitCardRequestValidator (FluentValidation) so failures surface as our EmbedProblemDetails.
A structurally absent required member still yields the framework's default 400 during deserialization —
the same contract as the other issuance endpoints (e.g. credit cards).
The funding bank account (DDA) the card draws against.
Whether to provision a DIGITAL or PHYSICAL card. PHYSICAL requires a shipping address.
Available options:
DIGITAL, PHYSICAL Caller-defined external reference, forwarded verbatim to TSYS as the ExternalApplicationId so the partner's own identifier flows end to end. Free-form text, max 50 characters (TSYS limit).
Optional caller-defined display nickname for the card, persisted and returned. When omitted or blank/whitespace, a default label is derived from the card type ("Virtual card" for DIGITAL, "Physical card" for PHYSICAL).
Shipping address for a PHYSICAL card. Required for PHYSICAL, disallowed for DIGITAL.
Show child attributes
Show child attributes
The user the card is issued to. Cardholder identity (name, etc.) is sourced from this user's profile. Defaults to the calling user when omitted; required when the caller is not an individual user (e.g. application tokens), otherwise the request is rejected with a 400.
Response
Created
The card network (brand) an issued card runs on, such as Visa or Mastercard.
Available options:
UNKNOWN, VISA, MASTERCARD, DISCOVER, AMERICAN_EXPRESS Available options:
PENDING_ACTIVATION, ACTIVE, LOCKED, CLOSED Available options:
DIGITAL, PHYSICAL Was this page helpful?