Replace a card

POST

cards

{cardId}

replace

Replace a card

curl --request POST \
  --url https://api.slash.com/v2/cards/{cardId}/replace \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'x-legal-entity: <x-legal-entity>' \
  --data '
{
  "physical": {
    "secondLine": "Computer Services"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'x-legal-entity': '<x-legal-entity>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({physical: {secondLine: 'Computer Services'}})
};

fetch('https://api.slash.com/v2/cards/{cardId}/replace', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.slash.com/v2/cards/{cardId}/replace"

payload = { "physical": { "secondLine": "Computer Services" } }
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "x-legal-entity": "<x-legal-entity>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slash.com/v2/cards/{cardId}/replace"

	payload := strings.NewReader("{\n  \"physical\": {\n    \"secondLine\": \"Computer Services\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("x-legal-entity", "<x-legal-entity>")
	req.Header.Add("X-API-Key", "<api-key>")
	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))

}

{
  "id": "c_2rj4l7hmrrrcv",
  "type": "virtual",
  "status": "pending",
  "name": "Ads – Meta",
  "accountId": "sa_group_2rj4l7hmrrrcv",
  "singleUse": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "last4": "4242",
  "expiryMonth": 9,
  "expiryYear": 2030,
  "virtualAccountId": "subaccount_2rj4l7hmrrrcv",
  "cardGroupId": "card_group_2rj4l7hmrrrcv",
  "cardProductId": "card_product_2rj4l7hmrrrcv",
  "cardholderUserId": "u_2rj4l7hmrrrcv",
  "controls": {
    "limit": {
      "amount": {
        "amount": 500000,
        "currency": "USD"
      },
      "period": "monthly"
    },
    "transactionLimit": {
      "amount": 250000,
      "currency": "USD"
    },
    "merchantCategoryCodes": {
      "mode": "block",
      "values": [
        "7995"
      ]
    }
  },
  "billingAddress": {
    "line1": "<string>",
    "city": "<string>",
    "line2": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>"
  },
  "physical": {
    "design": "plastic",
    "secondLine": "Computer Services",
    "shipping": {
      "address": {
        "line1": "<string>",
        "city": "<string>",
        "line2": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "countryCode": "<string>"
      },
      "service": "standard",
      "status": "pending",
      "carrier": "fedex",
      "trackingNumber": "<string>",
      "trackingUrl": "<string>",
      "shippedAt": "2023-11-07T05:31:56Z"
    }
  },
  "closedReason": "no_longer_needed",
  "closedAt": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key

string

header

required

User API key authentication. Create a key under Settings → API keys in the Slash dashboard (https://app.slash.com/global-settings/api-keys) and send the x-legal-entity header naming the legal entity to act on with every request. Keys scoped to a legal entity are rejected with 403 user_api_key_required.

Headers

X-Idempotency-Key

string

required

Unique caller-generated key for one create request. Once an authenticated, schema-valid request reaches the operation, the key is permanently consumed for that operation and legal entity whether the operation succeeds or fails. Reusing it in that scope returns 409 and never replays a response, unlike API v1, which replays the original response for a matching key.

Required string length: 1 - 255

x-legal-entity

string

required

The legal entity to act on. Required on every request; a user API key can act on any legal entity its user has access to.

Pattern: ^le_[a-zA-Z0-9]+$

Path Parameters

cardId

string

required

Card id with the c_ prefix.

Body

application/json

The new card keeps the original's name, holder, account, virtual account, card group, design and spending limits and restrictions, and ships to the original's address with its second line unless physical sets them. Set a billing address or recurringPaymentsOnly, or change anything else, on the new card with PATCH /v2/cards/{cardId}.

reason

enum<string>

required

Why the card is replaced. The original closes with it as its closedReason.

Available options:

lost_or_stolen,

never_arrived,

damaged

physical

object

Hide child attributes

physical.secondLine

string

The line embossed under the holder's name.

Required string length: 1 - 19

Pattern: ^[A-Za-z0-9\-'& ]+$

Example:

"Computer Services"

physical.shipping

object

Hide child attributes

physical.shipping.address

Address · object

required

US addresses need a state and a postal code.

Hide child attributes

physical.shipping.address.line1

string

required

Minimum string length: 1

physical.shipping.address.city

string

required

Minimum string length: 1

physical.shipping.address.line2

string

physical.shipping.address.state

string

physical.shipping.address.postalCode

string

physical.shipping.address.countryCode

string

ISO 3166-1 alpha-2 country code.

Required string length: 2

physical.shipping.service

enum<string>

default:standard

priority ships to US addresses only.

Available options:

standard,

express,

priority

Response

The new card.

A virtual or physical card. Its number and security code are only available from GET /v2/cards/{cardId}/details.

string

required

Card id with the c_ prefix.

Example:

"c_2rj4l7hmrrrcv"

type

enum<string>

required

Available options:

virtual,

physical

status

enum<string>

required

pending: being issued, or waiting for a physical card's fee. awaiting_activation: a physical card its holder has not activated. active: approves authorizations. paused: declines them. inactive: deactivated by Slash or the issuer; can only be closed. closed: permanent.

Available options:

pending,

awaiting_activation,

active,

paused,

inactive,

closed

name

string

required

Example:

"Ads – Meta"

accountId

string

required

Account id with the sa_group_ prefix.

Example:

"sa_group_2rj4l7hmrrrcv"

singleUse

boolean

required

Whether the card closes after its first transaction. Virtual cards only.

createdAt

string<date-time>

required

last4

string

Absent on physical cards until they are activated.

Example:

"4242"

expiryMonth

integer

Example:

9

expiryYear

integer

Example:

2030

virtualAccountId

string

Virtual account the card spends from, with the subaccount_ prefix.

Example:

"subaccount_2rj4l7hmrrrcv"

cardGroupId

string

Card group id with the card_group_ prefix.

Example:

"card_group_2rj4l7hmrrrcv"

cardProductId

string

Card product id with the card_product_ prefix.

Example:

"card_product_2rj4l7hmrrrcv"

cardholderUserId

string

The user who holds the card, with the u_ prefix.

Example:

"u_2rj4l7hmrrrcv"

controls

CardControls · object

What the card may spend. The controls of its card group apply too. Replaced whole on update; null clears it.

Hide child attributes

controls.limit

CardControlsLimit · object

How much may be spent per period.

Hide child attributes

controls.limit.amount

UsdMoney · object

required

A positive USD amount expressed in cents.

Hide child attributes

controls.limit.amount.amount

integer

required

Amount in cents. For example, 1250 represents USD 12.50.

Required range: x >= 1

Example:

1250

controls.limit.amount.currency

enum<string>

required

Available options:

USD

controls.limit.period

enum<string>

required

Every period but lifetime resets at its boundary in timezone; lifetime never resets.

Available options:

daily,

weekly,

monthly,

yearly,

lifetime

controls.limit.startDate

string<date>

Day the first period starts, today or earlier. Defaults to the start of the current period. Not used by daily.

Example:

"2026-09-01"

controls.limit.timezone

string

IANA timezone the period boundaries use. Defaults to UTC.

Example:

"America/Los_Angeles"

controls.transactionLimit

UsdMoney · object

The most a single transaction may be.

Hide child attributes

controls.transactionLimit.amount

integer

required

Amount in cents. For example, 1250 represents USD 12.50.

Required range: x >= 1

Example:

1250

controls.transactionLimit.currency

enum<string>

required

Available options:

USD

controls.merchantCategories

CardControlsRestriction · object

Merchant category ids from GET /v2/merchant-categories.

Hide child attributes

controls.merchantCategories.mode

enum<string>

required

Available options:

allow,

block

controls.merchantCategories.values

string[]

required

Minimum array length: 1

controls.merchantCategoryCodes

CardControlsRestriction · object

Four-digit merchant category codes (MCC).

Hide child attributes

controls.merchantCategoryCodes.mode

enum<string>

required

Available options:

allow,

block

controls.merchantCategoryCodes.values

string[]

required

Minimum array length: 1

controls.merchants

CardControlsRestriction · object

Merchant ids from GET /v2/merchants.

Hide child attributes

controls.merchants.mode

enum<string>

required

Available options:

allow,

block

controls.merchants.values

string[]

required

Minimum array length: 1

controls.countries

CardControlsRestriction · object

ISO 3166-1 alpha-2 codes of merchant countries.

Hide child attributes

controls.countries.mode

enum<string>

required

Available options:

allow,

block

controls.countries.values

string[]

required

Minimum array length: 1

controls.recurringPaymentsOnly

boolean

Approve recurring payments only. An Enterprise feature.

Example:

{
  "limit": {
    "amount": { "amount": 500000, "currency": "USD" },
    "period": "monthly"
  },
  "transactionLimit": { "amount": 250000, "currency": "USD" },
  "merchantCategoryCodes": { "mode": "block", "values": ["7995"] }
}

billingAddress

Address · object

The address checked by address verification (AVS). Absent when the legal entity's address is used.

Hide child attributes

billingAddress.line1

string

required

Minimum string length: 1

billingAddress.city

string

required

Minimum string length: 1

billingAddress.line2

string

billingAddress.state

string

billingAddress.postalCode

string

billingAddress.countryCode

string

ISO 3166-1 alpha-2 country code.

Required string length: 2

physical

object

Present on physical cards.

Hide child attributes

physical.design

enum<string>

required

Available options:

plastic,

silver_metal,

gold_metal

physical.secondLine

string

The line embossed under the holder's name.

Example:

"Computer Services"

physical.shipping

object

Hide child attributes

physical.shipping.address

Address · object

required

Hide child attributes

physical.shipping.address.line1

string

required

Minimum string length: 1

physical.shipping.address.city

string

required

Minimum string length: 1

physical.shipping.address.line2

string

physical.shipping.address.state

string

physical.shipping.address.postalCode

string

physical.shipping.address.countryCode

string

ISO 3166-1 alpha-2 country code.

Required string length: 2

physical.shipping.service

enum<string>

required

Available options:

standard,

express,

priority

physical.shipping.status

enum<string>

required

pending: ordered, not yet shipped.

Available options:

pending,

shipped,

canceled

physical.shipping.carrier

enum<string>

Available options:

fedex,

usps

physical.shipping.trackingNumber

string

physical.shipping.trackingUrl

string

physical.shipping.shippedAt

string<date-time>

closedReason

enum<string>

Available options:

no_longer_needed,

lost_or_stolen,

never_arrived,

damaged,

closed_by_slash

closedAt

string<date-time>

⌘I

Replace a card

curl --request POST \
  --url https://api.slash.com/v2/cards/{cardId}/replace \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'x-legal-entity: <x-legal-entity>' \
  --data '
{
  "physical": {
    "secondLine": "Computer Services"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'x-legal-entity': '<x-legal-entity>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({physical: {secondLine: 'Computer Services'}})
};

fetch('https://api.slash.com/v2/cards/{cardId}/replace', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.slash.com/v2/cards/{cardId}/replace"

payload = { "physical": { "secondLine": "Computer Services" } }
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "x-legal-entity": "<x-legal-entity>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slash.com/v2/cards/{cardId}/replace"

	payload := strings.NewReader("{\n  \"physical\": {\n    \"secondLine\": \"Computer Services\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("x-legal-entity", "<x-legal-entity>")
	req.Header.Add("X-API-Key", "<api-key>")
	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))

}

{
  "id": "c_2rj4l7hmrrrcv",
  "type": "virtual",
  "status": "pending",
  "name": "Ads – Meta",
  "accountId": "sa_group_2rj4l7hmrrrcv",
  "singleUse": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "last4": "4242",
  "expiryMonth": 9,
  "expiryYear": 2030,
  "virtualAccountId": "subaccount_2rj4l7hmrrrcv",
  "cardGroupId": "card_group_2rj4l7hmrrrcv",
  "cardProductId": "card_product_2rj4l7hmrrrcv",
  "cardholderUserId": "u_2rj4l7hmrrrcv",
  "controls": {
    "limit": {
      "amount": {
        "amount": 500000,
        "currency": "USD"
      },
      "period": "monthly"
    },
    "transactionLimit": {
      "amount": 250000,
      "currency": "USD"
    },
    "merchantCategoryCodes": {
      "mode": "block",
      "values": [
        "7995"
      ]
    }
  },
  "billingAddress": {
    "line1": "<string>",
    "city": "<string>",
    "line2": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>"
  },
  "physical": {
    "design": "plastic",
    "secondLine": "Computer Services",
    "shipping": {
      "address": {
        "line1": "<string>",
        "city": "<string>",
        "line2": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "countryCode": "<string>"
      },
      "service": "standard",
      "status": "pending",
      "carrier": "fedex",
      "trackingNumber": "<string>",
      "trackingUrl": "<string>",
      "shippedAt": "2023-11-07T05:31:56Z"
    }
  },
  "closedReason": "no_longer_needed",
  "closedAt": "2023-11-07T05:31:56Z"
}

Banking

Money movement

Cards

Bill pay

Invoicing

Accounting

Platform

Replace a card

Authorizations

Headers

Path Parameters

Body

Response