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",
"capabilities": {
"activate": true,
"billingAddress": true,
"close": true,
"credentials": true,
"lock": true,
"merchantCategoryGroups": true,
"velocityControls": true
},
"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>",
"statusReason": "LOST"
}{
"errorCode": "<string>",
"detail": "<string>",
"errors": {},
"instance": "<string>",
"questionErrors": [
{
"code": "REQUIRED",
"message": "<string>",
"itemPath": "<string>",
"key": "<string>",
"ownerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"requirementsVersion": "<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>"
}{
"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
/
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",
"capabilities": {
"activate": true,
"billingAddress": true,
"close": true,
"credentials": true,
"lock": true,
"merchantCategoryGroups": true,
"velocityControls": true
},
"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>",
"statusReason": "LOST"
}{
"errorCode": "<string>",
"detail": "<string>",
"errors": {},
"instance": "<string>",
"questionErrors": [
{
"code": "REQUIRED",
"message": "<string>",
"itemPath": "<string>",
"key": "<string>",
"ownerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"requirementsVersion": "<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>"
}{
"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, unique per organization: repeating a request with the same reference returns the card it issued instead of issuing another, and reusing it for a different request is a 409. Forwarded verbatim to TSYS as the ExternalApplicationId. 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
Which operations the card's provider supports. A true value does not mean the card's current status
allows the operation: a closed card still reports lock when its provider supports locking.
Show child attributes
Show child attributes
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 Why the card is LOCKED or CLOSED, when a reason was given. Null otherwise.
Available options:
LOST, STOLEN, FRAUD, CARDHOLDER_EXIT, REPLACED, EXPIRED Was this page helpful?