Update a card
PATCH/profile/prepaid/cards/:cardId
Overview
The endpoint enables updating a card’s state like status and PIN.
SCA Authentication
The necessity for SCA Authentication arises when customers need to adhere to the particular regulations outlined in the PSD2 directive.
The HTTP WWW-Authenticate
response header defines the SCA authentication methods that might be used to gain
access to the specific resource:
HTTP/2 401 Unauthorized
WWW-Authenticate: SCA realm="Prepaid Cards" auth-param1="ewogICJzY2FEZXRhaWxzIjogewogICAgImV2ZW50SWQiOiAiMDZiZGMyYzAtY2NlLTRiMzYtOTdlYy0yODFjOGY1ZDc0M2MiLAogICAgIndhbGxldE9wZXJhdGlvbklkIjogImE1ODY1ZmQ2LTE4YzItNDVhOC05OTUzLTFjMDBlYWMzNmMzNiIsCiAgICAiYXV0aGVudGljYXRpb25Nb2RlIjogIk9VVFNPVVJDRUQiLAogICAgImF2YWlsYWJsZVZlcmlmaWNhdGlvbnMiOiBbCiAgICAgIHsKICAgICAgICAibWV0aG9kIjogIlBJTiIKICAgICAgfSwKICAgICAgewogICAgICAgICJtZXRob2QiOiAiT1RQIiwKICAgICAgICAiY2hhbm5lbCI6ICJTTVMiCiAgICAgIH0KICAgIF0sCiAgICAiY3JlYXRpb25UaW1lIjogIjIwMjEtMDctMTVUMTc6NTQ6MTJaIiwKICAgICJleHBpcmF0aW9uVGltZSI6ICIyMDIxLTA3LTE1VDE4OjA5OjEyWiIKICB9Cn0="
Upon the successful completion of the SCA authentication process, the user should re-request the same wallet
resource. This should be done using the SCA-Authorization
request header:
POST /digitalwallets/v1/auth/brands/{brandIdentity}/token HTTP/2
Host: api.paysafe.com
SCA-Authorization: ewogICJzY2FEZXRhaWxzIjogewogICAgImV2ZW50SWQiOiAiMDZiZGNkMmMtMGNjZS00YjM2LTk3ZWMtMjgxYzhmNWQ3NDNjIiwKICAgICJ3YWxsZXRPcGVyYXRpb25JZCI6ICJhNTg2NWZkNi0xOGMyLTQ1YTgtOTk1My0xYzAwZWFjMzZjMzYiCn0=
More details can be found in Strong Customer Authentication.
Request
Path Parameters
UUID based Card id.
- application/json
Body
Depending on the provided fields in the request, update will be performed on the desired card.
Updating a card status requires two fields to be provided in the request:
- status
- statusReason
Changing the PIN of a physical card requires only pin
field to be provided.
VIRTUAL card type supports only the following card statuses:
- ACTIVE
- CANCELLED
- LOCKED
PHYSICAL card type supports all of the allowed values:
-
ACTIVE
-
CANCELLED
-
LOCKED
ACTIVE
- Card can be used for payments.PENDING
- Intermediate status before issuing a card, while performing additional validations.CANCELLED
- The card is canceled and can't be used for any kind of operation. The status is (IRREVERSIBLE).SUSPENDED
- The status is changed from CS (Customer Service) representative or due to customer actions like (wrong activation info).APPLIED
- Intermediate status for a card that is stuck due to technical reasons.DIGITAL
-PHYSICAL
card that is active and can be used for online payments only, but it is not yet delivered to the client, and it is not activated.REJECTED
- Card is rejected due to technical / validation reasons.LOCKED
- Card is locked by the customer and can't be used for payments.EXPIRED
- Card is expired.ISSUED
- The status indicates that the customer has successfully applied for aPHYSICAL
card, but the card is not yet activated and can't be used for payments.
Possible values: [ACTIVE
, PENDING
, CANCELLED
, SUSPENDED
, APPLIED
, DIGITAL
, REJECTED
, LOCKED
, EXPIRED
, ISSUED
]
Contain information about the different card statuses.
Possible values: <= 200 characters
The reason for card status change.
Possible values: >= 4 characters
and <= 4 characters
The Card pin should be 4 digits.
Possible values: <= 1000 characters
The User Agent used for the request. The field should follow the official specification - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent#syntax
Responses
- 200
- 400
- 401
- 404
- 405
- 500
OK
- application/json
- Schema
- Example (from schema)
- UPDATED_CARD
Schema
ACTIVE
- Card can be used for payments.PENDING
- Intermediate status before issuing a card, while performing additional validations.CANCELLED
- The card is canceled and can't be used for any kind of operation. The status is (IRREVERSIBLE).SUSPENDED
- The status is changed from CS (Customer Service) representative or due to customer actions like (wrong activation info).APPLIED
- Intermediate status for a card that is stuck due to technical reasons.DIGITAL
-PHYSICAL
card that is active and can be used for online payments only, but it is not yet delivered to the client, and it is not activated.REJECTED
- Card is rejected due to technical / validation reasons.LOCKED
- Card is locked by the customer and can't be used for payments.EXPIRED
- Card is expired.ISSUED
- The status indicates that the customer has successfully applied for aPHYSICAL
card, but the card is not yet activated and can't be used for payments.- VISA - VISA
- MC - Mastercard The scheme is derived from the card PAN.
Array [
]
Card id is a unique identifier for a specific card. It will be used for most operations to the prepaid card.
Possible values: [ACTIVE
, PENDING
, CANCELLED
, SUSPENDED
, APPLIED
, DIGITAL
, REJECTED
, LOCKED
, EXPIRED
, ISSUED
]
Contain information about the different card statuses.
expiry
object
Card expiry date.
Card bin.
Possible values: >= 4 characters
and <= 4 characters
Card last four digits.
Wallet customer ID.
Possible values: [PHYSICAL
, VIRTUAL
]
Supported card types. Currently we support only VIRTUAL
and PHYSICAL
Card program name.
Possible values: >= 3 characters
and <= 3 characters
Card currency code.
Possible values: Value must match regular expression ^\+\d+\s?\d{1,16}$
Mobile phone number used during card creation.
deliveryAddress
object
The DeliveryAddress object will be used for the PHYSICAL
card delivery. It must be null in case of VIRTUAL
card
Possible values: >= 4 characters
and <= 40 characters
Possible values: <= 30 characters
Possible values: <= 30 characters
Possible values: <= 30 characters
Max 30 characters: letters, spaces, hyphen and period
Possible values: >= 2 characters
and <= 2 characters
Country code in ISO-3166 Alpha 2
Possible values: <= 3 characters
The field is mandatory for US Customers: 2 to 3 characters state or province abbreviation. Example: "UT"
Possible values: non-empty
and <= 16 characters
For EU customers: maximum length 16
For US customers: Pattern: ^[a-zA-Z0-9-\ ]*$
minimum 4, maximum 10
Card created date in ISO 8601 format. Example: 2022-10-04T11:14:47.596Z
accountId is used for Multi-Currency Accounts.
Possible values: [VISA
, MC
]
Card scheme information.
When PHYSICAL
card has been activated. ISO 8601 format.
Indicates that the card PIN has been set or not.
External identifier in merchant system.
tokenizations
object
Contains a list of Mobile Wallet Tokenizations
mobileWalletTokenizations
object[]
Contains information about card enrolments for specific Mobile Wallet
dpan (Device Pan) reference.
Wallet Id used only with Google Pay.
Possible values: [GOOGLE_PAY
, APPLE_PAY
, SAMSUNG_PAY
]
Contains supported wallet types.
Possible values: [COMPLETED
, INITIATED
]
Mobile wallet status type.
{
"cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "ACTIVE",
"expiry": {
"month": 3,
"year": 2028
},
"bin": "string",
"lastFour": "string",
"customerId": "string",
"cardType": "PHYSICAL",
"programName": "string",
"currency": "string",
"mobile": "string",
"deliveryAddress": {
"address1": "Tsarigradsko Shose 73",
"address2": "floor 3",
"address3": "apartment 43",
"city": "Sofia",
"countryCode": "BG",
"state": "UT",
"postalCode": "1000"
},
"createdDate": "2024-09-17T12:55:46.926Z",
"accountId": "string",
"scheme": "VISA",
"activationDate": "2024-09-17T12:55:46.926Z",
"isPinSet": true,
"externalId": "string",
"tokenizations": {
"mobileWalletTokenizations": [
{
"dpanRef": "DAPLMC00002125433c0c34a2821f4f86866e7576963baf8b",
"walletId": "NMZlGi8-DezZZKaU06orvl0f",
"walletType": "GOOGLE_PAY",
"status": "COMPLETED"
}
]
}
}
{
"cardId": "f16ba382-eb42-481a-b08f-c57bdc9aae24",
"status": "ACTIVE",
"expiry": {
"month": 3,
"year": 2028
},
"bin": "533944",
"lastFour": "7009",
"customerId": "12345678",
"cardType": "VIRTUAL",
"programName": "BRAND-VIRTUAL-MC-EEA",
"currency": "EUR",
"mobile": "+359 888333333",
"createdDate": "2019-08-24T14:15:22Z",
"accountId": "127623047",
"scheme": "VISA",
"activationDate": "2019-08-24T14:15:22Z",
"isPinSet": false,
"externalId": "a2322550-af91-417f-867e-681efad44b9d"
}
Bad Request
- application/json
- Schema
- Example (from schema)
- STATUS_NOT_ALLOWED
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-PREPAID-CARDS-STATUS-NOT-ALLOWED",
"message": "Card status is not allowed for the current card type.",
"details": [
"Card status is not allowed for the current card type."
],
"fieldErrors": []
}
}
Unauthorized
Response Headers
WWW-Authenticate
string
Specifies the necessity of employing the
SCA
security scheme within the specific wallet domain.
- application/json
- Schema
- Example (from schema)
- SCA_VERIFICATION_FAILED
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-SCA-VERIFICATION-FAILED",
"message": "The wallet operation was unsuccessful.",
"details": [
"The wallet operation was declined because the SCA requirement is not completed."
]
}
}
Not Found
- application/json
- Schema
- Example (from schema)
- CARD_NOT_FOUND
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "5269",
"message": "Entity not found",
"details": [
"The ID(s) specified in the URL do not correspond to the values in the system."
],
"fieldErrors": []
}
}
Method Not Allowed
- application/json
- Schema
- Example (from schema)
- DW-OPERATION-NOT-ALLOWED
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-OPERATION-NOT-ALLOWED",
"message": "Operation is not allowed in your account. Contact Paysafe for further details.",
"details": [
"Operation is not allowed in your account. Contact Paysafe for further details."
]
}
}
Internal Server Error
- application/json
- Schema
- Example (from schema)
- INTERNAL_SERVER_ERROR
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-INTERNAL-SERVER-ERROR",
"message": "Internal Server Error.",
"details": [
"Internal Server Error."
],
"fieldErrors": []
}
}