Cards

The Card resource represents a card under an account.

info

Unit provides a cross-platform suite of flexible and customizable white-label UI components, including a card component. You may embed the card component into your app to shorten your time to market and deliver a highly optimized experience to your end customer with minimal engineering investment.

note

Unit enables you to programmatically review card Authorization Requests when they are made, and decide whether to approve the purchase. This capability gives complete control and visibility into card use.

Card Resource Types

There are multiple types of card resources on Unit, each solves for specific use cases. The table below outlines the different types and use cases.

Type	Details
IndividualVirtualDebitCard	A virtual debit card belonging to an Individual customer, including sole proprietors. The details of the card holder (name, email, phone number etc.) will be the individual customer's details.
IndividualDebitCard	A physical debit card belonging to an Individual customer, including sole proprietors. The details of the card holder (name, email, phone number etc.) will be the individual customer's details and by default the card will be shipped to the customer's address.
BusinessVirtualDebitCard	A virtual debit card belonging to a Business customer. The card holder may be any person associated with the business. The details of the card holder (name, email, phone number etc.) will be provided as part of the card creation request. In order to create the customer token that is needed to reveal the card information, the card holder must be the business contact or an (authorized user)[/api/customers/#authorized-users].
BusinessDebitCard	A physical debit card belonging to a Business customer. The card holder may be any person associated with the business. The details of the card holder (name, email, phone number etc.) and shipping address will be provided as part of the card creation request.
BusinessVirtualCreditCard	A virtual credit card belonging to a Business customer. The card holder may be any person associated with the business. The details of the card holder (name, email, phone number etc.) will be provided as part of the card creation request. In order to create the customer token that is needed to reveal the card information, the card holder must be the business contact or an authorized user.
BusinessCreditCard	A physical credit card belonging to a Business customer. The card holder may be any person associated with the business. The details of the card holder (name, email, phone number etc.) and shipping address will be provided as part of the card creation request.

info

Cards issued to sole proprietors are business cards for all intents and purposes (BIN, interchange etc.)

Card Statuses

Cards have a Status Property, which represent their current status and determines what actions can or can't be completed using the card.

Status	Description	Comments
Inactive	The Card has not been activated by the Customer	Cards can be activated using the Activate card or by calling a the toll-free number printed on the card. Virtual cards do not require activation.
Active	The Card has been activated and can be used regularly
Stolen	The Card has been reported stolen by the Customer	A stolen card cannot be reopened.
Lost	The Card has been reported lost by the customer	A lost card cannot be reopened.
Frozen	The Card has been frozen
ClosedByCustomer	The Card has been closed by the Customer	A closed card cannot be reopened.
SuspectedFraud	The Card has been flagged due to fraud suspicion	Cards are defined as "SuspectedFraud" by the card network (e.g. Visa). The network will reach out to the client to confirm recent transactions that were marked as potentially fraudulent and reactivate the card if the transactions are confirmed as not fraudulent. If the transactions are marked as fraudulent or if the client does not respond to the card network, the card will remain in SuspectedFraud status and cannot be used.

info

One month before a card (physical or virtual) is due to expire the network and card printer (for physical cards) will automatically re-issue a new card with the same card number, the new expiration date and the new CVV.

Cards are excluded from automatic re-reissue if one of these conditions applies:

The status is not active (i.e., stolen, lost, frozen, closed by customer, suspected fraud)
The card has not been activated by the customer (i.e., inactive)
There is no card activity in the last 6 months - this includes all card related transactions

The new cards are issued with 4 year validity. Virtual cards are issued ready to use instantly. New physical cards require to be activated by the customer before the first use. Activation of the new card blocks the old cards from being used further.

Create Individual Debit Card

Creates and ships a physical debit card to an individual. You must link the card to an account using the account field under relationships object. The linked account must belong to an individual customer (and not a business). The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

For security reasons, an individual customer's account may have up to one physical card in Active or newly created (Inactive) status.

To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`individualDebitCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
shippingAddress	Address	Optional. Address to ship the card to. If not specified, the individual address is used.
design	string	Optional. You may omit if you only have one card design. Please contact Unit if you need multiple card designs.
additionalEmbossedText	string	Optional, up to 21 characters. Use for a second cardholder name, company name, or other data to be embossed on a card.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
printOnlyBusinessName	boolean	Optional, default is `false`. Print the business name on the card instead of the card holder's name. Available only for Sole Proprietorship typed customers that have a DBA property.
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.

Relationships

Name	Type	Description
account	JSON:API Relationship	Link to the account the card belongs to. Holder of the account must be an individual.
customer	JSON:API Relationship	Optional, Link to the customer the card belongs to. Mandatory if the account has more than one customer. Holder of the account must be an individual.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "individualDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8",
      "limits": {
        "dailyWithdrawal": 50000,
        "dailyPurchase": 50000,
        "monthlyWithdrawal": 500000,
        "monthlyPurchase": 700000
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	IndividualDebitCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "individualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "bin": "123456789",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "2"
        }
      }
    }
  }
}

Create Business Debit Card

Creates and ships a physical debit card to a business card holder. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer. The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

When creating a business debit card, the card holder's personal information must be provided as part of the request.

note

For security reasons, a card holder of a business debit card may have up to one physical card in Active or newly created (Inactive) status.

To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`businessDebitCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
fullName	FullName	Full name of the card holder.
dateOfBirth	RFC3339 Date string	Date of birth of the card holder (e.g. `"2001-08-15"`).
address	Address	Address of the card holder.
shippingAddress	Address	Optional. Address to ship the card to. If not specified, card holder address is used.
phone	Phone	Phone of the card holder.
email	string	Email address of the card holder.
design	string	Optional. You may omit if you only have one card design. Please contact Unit if you need multiple card designs.
additionalEmbossedText	string	Optional, up to 21 characters. Use for a second cardholder name, company name, or other data to be embossed on a card.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
printOnlyBusinessName	boolean	Optional, default is `false`. Print the business name on the card instead of the card holder's name.
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.
ssn	string	Optional. SSN (or ITIN) of the individual (numbers only). Either an `ssn` or `passport` is required. It is optional to provide only last 4 SSN digits.
passport	string	Optional. Passport number of the individual. Valid only for non-US persons.
nationality	ISO31661-Alpha2 string	Required if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").

Relationships

Name	Type	Description
account	JSON:API Relationship	The account the card belongs to. Holder of the account must be a business.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8",
      "limits": {
        "dailyWithdrawal": 50000,
        "dailyPurchase": 50000,
        "monthlyWithdrawal": 500000,
        "monthlyPurchase": 700000
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	BusinessDebitCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "businessDebitCard",
    "id": "9",
    "attributes": {
      "createdAt": "2020-05-13T09:42:21.857Z",
      "last4Digits": "2074",
      "expirationDate": "2022-05",
      "bin": "123456789",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555666"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1"
        }
      }
    }
  }
}

Create Business Credit Card

Creates and ships a physical credit card to a business card holder. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer. The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

When creating a business credit card, the card holder's personal information must be provided as part of the request.

note

For security reasons, a card holder of a business credit card may have up to one physical card in Active or newly created (Inactive) status. To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`businessCreditCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
fullName	FullName	Full name of the card holder.
dateOfBirth	RFC3339 Date string	Date of birth of the card holder (e.g. `"2001-08-15"`).
address	Address	Address of the card holder.
shippingAddress	Address	Optional. Address to ship the card to. If not specified, card holder address is used.
phone	Phone	Phone of the card holder.
email	string	Email address of the card holder.
design	string	Optional. You may omit if you only have one card design. Please contact Unit if you need multiple card designs.
additionalEmbossedText	string	Optional, up to 21 characters. Use for a second cardholder name, company name, or other data to be embossed on a card.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
printOnlyBusinessName	boolean	Optional, default is `false`. Print the business name on the card instead of the card holder's name.
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.
ssn	string	Optional. SSN (or ITIN) of the individual (numbers only). Either an `ssn` or `passport` is required. It is optional to provide only last 4 SSN digits.
passport	string	Optional. Passport number of the individual. Valid only for non-US persons.
nationality	ISO31661-Alpha2 string	Required if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").

Relationships

Name	Type	Description
account	JSON:API Relationship	The account the card belongs to. Holder of the account must be a business.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessCreditCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8",
      "limits": {
        "dailyWithdrawal": 50000,
        "dailyPurchase": 50000,
        "monthlyWithdrawal": 500000,
        "monthlyPurchase": 700000
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "creditAccount",
          "id": "1"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	BusinessCreditCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "businessCreditCard",
    "id": "10",
    "attributes": {
      "createdAt": "2023-12-19T11:59:25.574Z",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "last4Digits": "4304",
      "expirationDate": "2027-12",
      "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "status": "Inactive"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10000"
        }
      }
    }
  }
}

Create Individual Virtual Debit Card

Creates a debit card for an individual. You must link the card to an account using the account field under relationships object. The linked account must belong to an individual customer (and not a business). The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

For security reasons, an individual customer's account may have up to one virtual card in Active status.

To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

note

Unlike physical cards, virtual cards are created in Active status and do not require activation.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`individualVirtualDebitCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.

Relationships

Name	Type	Description
account	JSON:API Relationship	Link to the account the card belongs to. Holder of the account must be an individual.
customer	JSON:API Relationship	Optional, Link to the customer the card belongs to. Mandatory if the account has more than one customer. Holder of the account must be an individual.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "individualVirtualDebitCard",
    "attributes": {
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8",
      "limits": {
        "dailyWithdrawal": 50000,
        "dailyPurchase": 50000,
        "monthlyWithdrawal": 500000,
        "monthlyPurchase": 700000
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	IndividualVirtualDebitCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "individualVirtualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "status": "Active",
      "bin": "123456789"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "2"
        }
      }
    }
  }
}

Create Business Virtual Debit Card

Creates a debit card for a business. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer. The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

When creating a business debit card, the card holder's personal information must be provided as part of the request.

note

For security reasons, a card holder of a business debit card may have up to one virtual card in Active or newly created (Inactive) status.

To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

note

Unlike physical cards, virtual cards are created in Active status and do not require activation.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`businessVirtualDebitCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
fullName	FullName	Full name of the card holder.
dateOfBirth	RFC3339 Date string	Date of birth of the card holder (e.g. `"2001-08-15"`).
address	Address	Address of the card holder.
phone	Phone	Phone of the card holder.
email	string	Email address of the card holder.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.
ssn	string	Optional. SSN (or ITIN) of the individual (numbers only). Either an `ssn` or `passport` is required. It is optional to provide only last 4 SSN digits.
passport	string	Optional. Passport number of the individual. Valid only for non-US persons.
nationality	ISO31661-Alpha2 string	Required if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").

Relationships

Name	Type	Description
account	JSON:API Relationship	The account the card belongs to. Holder of the account must be a business.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessVirtualDebitCard",
    "attributes": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8",
      "limits": {
        "dailyWithdrawal": 50000,
        "dailyPurchase": 50000,
        "monthlyWithdrawal": 500000,
        "monthlyPurchase": 700000
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	BusinessVirtualDebitCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "businessVirtualDebitCard",
    "id": "9",
    "attributes": {
      "createdAt": "2020-05-13T09:42:21.857Z",
      "last4Digits": "2074",
      "expirationDate": "2022-05",
      "bin": "123456789",
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555666"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "status": "Active"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1"
        }
      }
    }
  }
}

Create Business Virtual Credit Card

Creates a credit card for a business. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer. The card creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

note

When creating a business credit card, the card holder's personal information must be provided as part of the request.

note

For security reasons, a card holder of a business credit card may have up to one virtual card in Active or newly created (Inactive) status. To change this policy in your org, please contact Unit. Cards that were reported lost, reported stolen or closed do not count as active.

note

Unlike physical cards, virtual cards are created in Active status and do not require activation.

Verb	`POST`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards-write`
Data Type	`businessVirtualCreditCard`
Timeout (Seconds)	`120`

Attributes

Name	Type	Description
fullName	FullName	Full name of the card holder.
dateOfBirth	RFC3339 Date string	Date of birth of the card holder (e.g. `"2001-08-15"`).
address	Address	Address of the card holder.
phone	Phone	Phone of the card holder.
email	string	Email address of the card holder.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags.
limits	object	Optional. See Limits (cents).
expiryDate	string	Optional. Expiration date of the card in one of the formats MM/yy or yyyy-MM or yy-MM (e.g. `"03/27"`). Must be between 3 to 5 years. Default is 4 years.
ssn	string	Optional. SSN (or ITIN) of the individual (numbers only). Either an `ssn` or `passport` is required. It is optional to provide only last 4 SSN digits.
passport	string	Optional. Passport number of the individual. Valid only for non-US persons.
nationality	ISO31661-Alpha2 string	Required if a passport is used as the main ID. Two letters representing the individual nationality. (e.g. "US").

Relationships

Name	Type	Description
account	JSON:API Relationship	The account the card belongs to. Holder of the account must be a business.

Example Request:
curl -X POST 'https://api.s.unit.sh/cards'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessVirtualCreditCard",
    "attributes": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb10"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "creditAccount",
          "id": "10000"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	BusinessVirtualCreditCard	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "businessVirtualCreditCard",
    "id": "10",
    "attributes": {
      "createdAt": "2023-12-19T12:02:17.148Z",
      "last4Digits": "4577",
      "expirationDate": "2027-12",
      "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "status": "Active"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10000"
        }
      }
    }
  }
}

Displaying Sensitive Card Data

In order to display sensitive card data (card number and CVV2) to a customer, without any of it passing through your systems (which would subject you to PCI compliance requirements), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

info

Displaying card number and CVV2 for physical debit cards is disabled by default for security reasons.

This functionality can be enabled on Unit dashboard at: Settings -> Org Settings -> General -> Show sensitive data for physical cards.

note

Displaying and setting of sensitive card data is only available for active cards.

VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Show which allows easy integration with your UI components. VGS Show offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to your cardholder.

The VGS Show JavaScript library enables you to securely display sensitive data in a webpage while safely isolating that sensitive data from your systems. VGS Show JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

Integration steps

Import the VGS Show library:

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.5/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>

Initialize the component:

const show = VGSShow.create('tntazhyknp1');

Vault ID:

Environment	Vault Id
Sandbox	`tntazhyknp1`
Live	`tnt8w6nrmbu`

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

caution

The customer token is required to include the cards-sensitive scope.

Unit recommends avoiding adding additional scopes to the token.

Provide a valid card identifier

path: '/cards/<CARD ID>/secure-data/cvv2'

Note: Timeout for this API is 120 seconds

Example of creating a Customer Token for sensitive data:
curl -X POST 'https://api.s.unit.sh/customers/8/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "cards-sensitive",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Example of displaying card number and CVV2:
<!DOCTYPE html>
<html>
<head>
    <meta charSet="utf-8">
    <title></title>
    <style>
        iframe {
            height: 20px;
        }
    </style>
</head>
<body>
<h2>Sensitive Data example</h2>
<label>Card Number:</label>
<div id="cardNumber"></div>
<label>CVV2:</label>
<div id="cvv2"></div>

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.5/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>
<script type="text/javascript">
    const show = VGSShow.create('tntazhyknp1');
    const customerToken = "<CUSTOMER TOKEN>";
    const cardId = "<CARD ID>";

    const cvv2iframe = show.request({
            name: 'data-text',
            method: 'GET',
            path: '/cards/' + cardId + '/secure-data/cvv2',
            headers: {
                "Authorization": "Bearer " + customerToken
            },
            htmlWrapper: 'text',
            jsonPathSelector: 'data.attributes.cvv2'
        });
    cvv2iframe.render('#cvv2');

    const cardNumberIframe = show.request({
            name: 'data-text',
            method: 'GET',
            path: '/cards/' + cardId + '/secure-data/pan',
            headers: {
                "Authorization": "Bearer " + customerToken
            },
            htmlWrapper: 'text',
            jsonPathSelector: 'data.attributes.pan'
        });
    cardNumberIframe.render('#cardNumber');
</script>
</body>
</html>

Activate Card

In order to activate a new card, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Collect which allows easy integration with your UI components. VGS Collect offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to the card processor.

VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

note

Unlike physical cards, virtual cards are created in Active status and do not require activation.

Integration steps

Import the VGS Collect library:

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

Initialize the component:

const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});

Parameters:

Environment	Vault Id	Environment Name
Sandbox	`tntazhyknp1`	`sandbox`
Live	`tnt8w6nrmbu`	`live`

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

caution

The customer token is required to include the cards-sensitive-write scope.

Unit recommends avoiding adding additional scopes to the token.

Provide a valid card identifier:

path: '/cards/<CARD ID>/activate'

Required field names and formats:

CVV2 field name should be data.attributes.cvv2.
Expiration Date field name should be data.attributes.expirationDate.
Expiration Date field format should be YYYY-MM.
Note: Timeout for this API is 120 seconds

Testing on Sandbox:

To simulate the scenario where the customer provides invalid data - send 1970-01 as the expiration date.
Sending anything other than that will result in a successful card activation.

Example of creating a Customer Token for Activate Card:
curl -X POST 'https://api.s.unit.sh/customers/8/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "cards-sensitive-write",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Example of Activate Card:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>VGS Collect Credit Card Example</title>

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
          integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

    <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

    <style>
        body {
            padding: 25px;
        }

        span[id*="cc-"] {
            display: block;
            height: 40px;
            margin-bottom: 15px;
        }

        span[id*="cc-"] iframe {
            height: 100%;
            width: 100%;
        }

        pre {
            font-size: 12px;
        }

        .form-field {
            display: block;
            width: 100%;
            height: calc(2.25rem + 2px);
            padding: .375rem .75rem;
            font-size: 1rem;
            line-height: 1.5;
            color: #495057;
            background-color: #fff;
            background-clip: padding-box;
            border: 1px solid #ced4da;
            border-radius: .25rem;
            transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
        }

        .form-field iframe {
            border: 0 none transparent;
            height: 100%;
            vertical-align: middle;
            width: 100%;
        }

        p {
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
<main>
    <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <div class="row card card-outline-secondary">
                <div class="card-body">
                    <h3 class="text-center">Activate Card</h3>
                    <hr>
                    <div class="alert alert-info p-2">
                        Please fill in and submit the form
                    </div>
                    <form id="cc-form">
                        <div class="form-group">
                            <label for="cc-cvv2">CVV2</label>
                            <span id="cc-cvv2" class="form-field">
                  <!--VGS Collect iframe for CVV2 field will be here!-->
                </span>
                            <label for="cc-expiration-date">Expiration Date</label>
                            <span id="cc-expiration-date" class="form-field">
                  <!--VGS Collect iframe for Expiration Date field will be here!-->
                </span>
                        </div>
                        <!--Submit form button-->
                        <button type="submit" class="btn btn-success btn-block">Submit</button>
                    </form>
                </div>
            </div>
        </div>
        <div class="col-md-4"></div>
    </div>
</main>

<!--Include script with VGS Collect form initialization-->
<script>
    // VGS Collect form initialization
    const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
    const customerToken = "<CUSTOMER TOKEN>";
    const cardId = "<CARD ID>";

    form.field('#cc-cvv2', {
        type: 'card-security-code',
        name: 'data.attributes.cvv2',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '123',
        maxLength: 3,
        validations: ['required', 'validCardSecurityCode']
    });

    form.field('#cc-expiration-date', {
        type: 'card-expiration-date',
        name: 'data.attributes.expirationDate',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: 'MM / YYYY',
        validations: ['required', 'validCardExpirationDate'],
        // Change to required experiation date format
        serializers: [form.SERIALIZERS.replace('(\\d{2})\\s\\/\\s(\\d{4})', '$2-$1')]
    });

    // Submit by executing a POST request.
    document.getElementById('cc-form')
        .addEventListener('submit', function(e) {
            e.preventDefault();
            form.submit('/cards/' + cardId + '/activate',
                {
                    // This converts the dot-separated field name strings into a JSON object
                    mapDotToObject: 'true',
                    headers: {
                        "Content-Type": "application/vnd.api+json",
                        "Authorization": "Bearer " + customerToken
                    }
                },


                function(status, data) {
                    console.log(data);
                });
        }, function (errors) {
            console.log(errors);
        });
</script>
</body>
</html>

Set PIN

Debit cards have a PIN that can be set through the API. The PIN must be set in order to allow cardholders to use their cards with PIN pads and ATMs.

caution

Credit cards do not currently support PINs.

In order to set a new PIN, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

info

In some instances, using a virtual debit card from a mobile wallet requires the user to provide a PIN (typically for larger purchases on a physical store, with a PIN pad). To support that use case, please give your cardholders the option to set their pin on virtual cards.

Integration steps

Import the VGS Collect library:

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

Initialize the component:

const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});

Parameters:

Environment	Vault Id	Environment Name
Sandbox	`tntazhyknp1`	`sandbox`
Live	`tnt8w6nrmbu`	`live`

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

caution

The customer token is required to include the cards-sensitive-write scope.

Unit recommends avoiding adding additional scopes to the token.

Provide a valid card identifier:

path: '/cards/<CARD ID>/secure-data/pin'

Required field names and formats:

PIN field name should be data.attributes.pin.
Note: Timeout for this API is 120 seconds

Example of creating a Customer Token for Set PIN:
curl -X POST 'https://api.s.unit.sh/customers/8/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "cards-sensitive-write",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Example of Set PIN:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Set PIN Example</title>

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
          integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

    <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

    <style>
        body {
            padding: 25px;
        }

        span[id*="cc-"] {
            display: block;
            height: 40px;
            margin-bottom: 15px;
        }

        span[id*="cc-"] iframe {
            height: 100%;
            width: 100%;
        }

        pre {
            font-size: 12px;
        }

        .form-field {
            display: block;
            width: 100%;
            height: calc(2.25rem + 2px);
            padding: .375rem .75rem;
            font-size: 1rem;
            line-height: 1.5;
            color: #495057;
            background-color: #fff;
            background-clip: padding-box;
            border: 1px solid #ced4da;
            border-radius: .25rem;
            transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
        }

        .form-field iframe {
            border: 0 none transparent;
            height: 100%;
            vertical-align: middle;
            width: 100%;
        }

        p {
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
<main>
    <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <div class="row card card-outline-secondary">
                <div class="card-body">
                    <h3 class="text-center">Set PIN</h3>
                    <hr>
                    <div class="alert alert-info p-2">
                        Please fill in and submit the form
                    </div>
                    <form id="cc-form">
                        <div class="form-group">
                            <label for="cc-pin">PIN</label>
                            <span id="cc-pin" class="form-field">
                  <!--VGS Collect iframe for PIN field will be here!-->
                </span>
                        </div>
                        <!--Submit form button-->
                        <button type="submit" class="btn btn-success btn-block">Submit</button>
                    </form>
                </div>
            </div>
        </div>
        <div class="col-md-4"></div>
    </div>
</main>

<!--Include script with VGS Collect form initialization-->
<script>
    // VGS Collect form initialization
    const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
    const customerToken = "<CUSTOMER TOKEN>";
    const cardId = "<CARD ID>";

    // Create VGS Collect field for PIN
    form.field('#cc-pin', {
        type: 'text',
        name: 'data.attributes.pin',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '1234',
        maxLength: 6,
        validations: ['required', '/^([0-9]{4,6})$/'],
    });

    // Submit by executing a POST request.
    document.getElementById('cc-form')
        .addEventListener('submit', function(e) {
            e.preventDefault();
            form.submit('/cards/' + cardId + "/secure-data/pin',
                {
                    // This converts the dot-separated field name string into a JSON object
                    mapDotToObject: 'true',
                    headers: {
                        "Content-Type": "application/vnd.api+json",
                        "Authorization": "Bearer " + customerToken
                    }
                },


                function(status, data) {
                    console.log(data);
                });
        }, function (errors) {
            console.log(errors);
        });
</script>
</body>
</html>

Get PIN Status

Gets the PIN status for the specified card.

If the returned status is NotSet, use Set PIN, otherwise use Change PIN.

Verb	`GET`
Url	`https://api.s.unit.sh/cards/{id}/secure-data/pin/status`
Required Scope	`cards` or `cards-sensitive`
Timeout (Seconds)	`120`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	PinStatus	PinStatus resource.

curl -X GET 'https://api.s.unit.sh/cards/5/secure-data/pin/status' \
-H "Authorization: Bearer ${TOKEN}"

Change PIN

In order to change an existing PIN, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

note

For security purposes, if there are 3 failed attempts to change a PIN within a 24 hour period the API will display a "Maximum number of attempts reached" error and the ability to change the PIN will be disabled for a 24 hour period.

Integration steps

Import the VGS Collect library:

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

Initialize the component:

const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});

Parameters:

Environment	Vault Id	Environment Name
Sandbox	`tntazhyknp1`	`sandbox`
Live	`tnt8w6nrmbu`	`live`

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

caution

The customer token is required to include the cards-sensitive-write scope.

Unit recommends avoiding adding additional scopes to the token.

Provide a valid card identifier:

path: '/cards/<CARD ID>/secure-data/pin'

Required field names and formats:

Old PIN field name should be data.attributes.oldPin.
New PIN field name should be data.attributes.newPin.

Example of creating a Customer Token for Change PIN:
curl -X POST 'https://api.s.unit.sh/customers/8/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "cards-sensitive-write",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Example of Change PIN:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Change PIN Example</title>

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
          integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

    <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.12.0/vgs-collect.js"></script>

    <style>
        body {
            padding: 25px;
        }

        span[id*="cc-"] {
            display: block;
            height: 40px;
            margin-bottom: 15px;
        }

        span[id*="cc-"] iframe {
            height: 100%;
            width: 100%;
        }

        pre {
            font-size: 12px;
        }

        .form-field {
            display: block;
            width: 100%;
            height: calc(2.25rem + 2px);
            padding: .375rem .75rem;
            font-size: 1rem;
            line-height: 1.5;
            color: #495057;
            background-color: #fff;
            background-clip: padding-box;
            border: 1px solid #ced4da;
            border-radius: .25rem;
            transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
        }

        .form-field iframe {
            border: 0 none transparent;
            height: 100%;
            vertical-align: middle;
            width: 100%;
        }

        p {
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
<main>
    <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <div class="row card card-outline-secondary">
                <div class="card-body">
                    <h3 class="text-center">Change PIN</h3>
                    <hr>
                    <div class="alert alert-info p-2">
                        Please fill in and submit the form
                    </div>
                    <form id="cc-form">
                        <div class="form-group">
                            <label for="cc-old-pin">Old PIN</label>
                            <span id="cc-old-pin" class="form-field">
                  <!--VGS Collect iframe for Old PIN field will be here!-->
                </span>
                        </div>
                        <div class="form-group">
                            <label for="cc-new-pin">New PIN</label>
                            <span id="cc-new-pin" class="form-field">
                  <!--VGS Collect iframe for New PIN field will be here!-->
                </span>
                        </div>
                        <!--Submit form button-->
                        <button type="submit" class="btn btn-success btn-block">Submit</button>
                    </form>
                </div>
            </div>
        </div>
        <div class="col-md-4"></div>
    </div>
</main>

<!--Include script with VGS Collect form initialization-->
<script>
    // VGS Collect form initialization
    const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
    const customerToken = "<CUSTOMER TOKEN>"

    // Create VGS Collect field for Old PIN
    form.field('#cc-old-pin', {
        type: 'text',
        name: 'data.attributes.oldPin',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '1234',
        maxLength: 6,
        validations: ['required', '/^([0-9]{4,6})$/'],
    });

    // Create VGS Collect field for New PIN
    form.field('#cc-new-pin', {
        type: 'text',
        name: 'data.attributes.newPin',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '1234',
        maxLength: 6,
        validations: ['required', '/^([0-9]{4,6})$/'],
    });

    // Submit by executing a PUT request.
    document.getElementById('cc-form')
        .addEventListener('submit', function(e) {
            e.preventDefault();
            form.submit('/cards/10001/secure-data/pin',
                {
                    method: 'PUT',
                    mapDotToObject: 'true',
                    headers: {
                        "Content-Type": "application/vnd.api+json",
                        "Authorization": "Bearer " + customerToken
                    }
                },


                function(status, data) {
                    console.log(data);
                });
        }, function (errors) {
            console.log(errors);
        });
</script>
</body>
</html>

Report Stolen

Report card as stolen.

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/report-stolen`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.

curl -X POST 'https://api.s.unit.sh/cards/6/report-stolen' \
-H "Authorization: Bearer ${TOKEN}"

Report Lost

Report card as lost.

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/report-lost`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.

curl -X POST 'https://api.s.unit.sh/cards/5/report-lost' \
-H "Authorization: Bearer ${TOKEN}"

Close Card

Close a card.

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/close`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.

curl -X POST 'https://api.s.unit.sh/cards/7/close' \
-H "Authorization: Bearer ${TOKEN}"

Freeze Card

Freeze a card (temporarily block a card).

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/freeze`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.

curl -X POST 'https://api.s.unit.sh/cards/8/freeze' \
-H "Authorization: Bearer ${TOKEN}"

Unfreeze Card

Unfreeze a frozen card.

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/unfreeze`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.

curl -X POST 'https://api.s.unit.sh/cards/8/unfreeze' \
-H "Authorization: Bearer ${TOKEN}"

Replace Card

Creates and ships a replacement physical debit card to an individual or business card holder. The replacement card has the same card number, expiration date and PIN as the original card, and does not require additional activation.

note

Only cards with statuses Active and Inactive can be replaced.

Verb	`POST`
Url	`https://api.s.unit.sh/cards/:cardId/replace`
Required Scope	`cards-sensitive-write` or `cards-write`
Data Type	`replaceCard`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
shippingAddress	Address	Optional. Temporary address to ship the replacement card to. If not specified, the address provided during card creation is reused. This will now effect the default `shippingAddress`

Example Request:
curl -X POST 'https://api.s.unit.sh/cards/8/replace'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "replaceCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      }
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard	Card resource, distinguished by the `type` field.

Example Response:
{
  "data": {
    "type": "individualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "2"
        }
      }
    }
  }
}

Get by Id

Get a card resource by id.

Verb	`GET`
Url	`https://api.s.unit.sh/cards/{id}`
Required Scope	`cards`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: `customer`, `account`. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Card resource, distinguished by the `type` field.
included	Array of DepositAccount or Customer	Array of resources requested by the `include` query parameter.

curl -X GET 'https://api.s.unit.sh/cards/1?include=customer' \
-H "Authorization: Bearer ${TOKEN}"

List

List cards. Filtering and paging can be applied.

Verb	`GET`
Url	`https://api.s.unit.sh/cards`
Required Scope	`cards`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Cards by Tags.
filter[status][]	string	(empty)	Optional. Filter cards by Card Status. Usage example: filter[status][0]=Stolen&filter[status][1]=Lost
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resources include: `customer`, `account`. See Getting Related Resources
sort	string	`sort=createdAt`	Optional. `sort=createdAt` for ascending order or `sort=-createdAt` (leading minus sign) for descending order.

curl -X GET 'https://api.s.unit.sh/cards?page[limit]=20&page[offset]=0&include=customer' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard	Array of card resources, distinguished by the `type` field.
included	Array of DepositAccount or Customer	Array of resources requested by the `include` query parameter.

Example Response:
{
  "data": [
    {
      "type": "individualDebitCard",
      "id": "1",
      "attributes": {
        "createdAt": "2020-05-10T16:45:02.272Z",
        "last4Digits": "1234",
        "expirationDate": "2022-05",
        "status": "Active"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "1"
          }
        },
        "customer": {
          "data": {
            "type": "individualCustomer",
            "id": "2"
          }
        }
      }
    },
    {
      "type": "businessDebitCard",
      "id": "4",
      "attributes": {
        "createdAt": "2020-05-10T20:37:48.069Z",
        "last4Digits": "1234",
        "expirationDate": "2022-05",
        "shippingAddress": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "phone": {
          "countryCode": "1",
          "number": "5555555789"
        },
        "email": "richard@piedpiper.com",
        "dateOfBirth": "2001-08-10",
        "ssn": "123456789",
        "status": "Active"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "1"
          }
        },
        "customer": {
          "data": {
            "type": "businessCustomer",
            "id": "1"
          }
        }
      }
    }
  ]
}

Update

Update a debit card.

note

Card creation requests are sent to the printer at 3AM EST daily. Therefore updates that are made past this time will only change the records but not the physical card.

Verb	`PATCH`
Url	`https://api.s.unit.sh/cards/:cardId`
Required Scope	`cards-write`
Timeout (Seconds)	`5`

Update Individual Debit Card

Name	Type	Description
shippingAddress	Address	Optional. Address to ship the card to. To modify or add specify the key and value. To delete a key specify the key name and `null` for the value.
design	string	Optional. Card design name. To modify or add specify the key and value.
tags	object	Optional. See Updating Tags.
limits	object	Optional. See Limits (cents).

Update Business Debit Card

Name	Type	Description
shippingAddress	Address	Optional. Address to ship the card to. To modify or add specify the key and value. To delete a key specify the key name and `null` for the value.
address	Address	Optional. Address of the card holder. To modify or add specify the new address.
phone	Phone	Optional. Phone of the card holder. To modify or add specify the new phone number.
email	string	Optional. Email address of the card holder. To modify or add specify the new email address.
design	string	Optional. Card design name. To modify or add specify the key and value.
tags	object	Optional. See Updating Tags.
limits	object	Optional. See Limits (cents).

Update Individual Virtual Debit Card

Name	Type	Description
tags	object	Optional. See Updating Tags.
limits	object	Optional. See Limits (cents).

Update Business Virtual Debit Card

Name	Type	Description
address	Address	Optional. Address of the card holder. To modify or add specify the new address.
phone	Phone	Optional. Phone of the card holder. To modify or add specify the new phone number.
email	string	Optional. Email address of the card holder. To modify or add specify the new email address.
tags	object	Optional. See Updating Tags.
limits	object	Optional. See Limits (cents).

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	IndividualDebitCard Or BusinessDebitCard Or BusinessVirtualDebitCard Or IndividualVirtualDebitCard resource	The target resource after the operation was completed.

Example of update business debit card:
curl -X PATCH 'https://api.s.unit.sh/cards/:cardId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555556"
      }
    }
  }
}'

Limits

Verb	`GET`
Url	`https://api.s.unit.sh/cards/:cardId/limits`
Timeout (Seconds)	`5`

curl -X GET 'https://api.s.unit.sh/cards/10104/limits' \
-H "Authorization: Bearer ${TOKEN}"

Card purchases and withdrawals can be subjected to daily and monthly amount limits. Limits are optional (by default there are no card-specific limits), and can be set when the card is created or updated. The limits are enforced by Unit, and once the limit is reached, the transaction will be rejected.

The daily limits reset at 12:00 a.m. on the timezone of relevant bank. The monthly limits are reset at the same time on the first of each month.

info

Card level limits card-specific are used to allow more granular control and flexibility. The account limits on card activity are enforced in addition to them, across all cards that belong to a certain account combined (i.e. a customer who owns two cards with card ATM Withdrawal Limits of $300 cannot withdraw $300 on both cards if their deposit product ATM Withdrawal Limit is set to $500).

{
  "data": {
    "type": "limits",
    "attributes": {
      "limits": {
        "dailyWithdrawal": 100000,
        "dailyPurchase": 200000,
        "monthlyWithdrawal": 5000000,
        "monthlyPurchase": 7000000
      },
      "dailyTotals": {
        "withdrawals": 3000,
        "deposits": 0,
        "purchases": 4000,
        "cardTransactions": 50000
      },
      "monthlyTotals": {
        "withdrawals": 120000,
        "deposits": 0,
        "purchases": 1400000,
        "cardTransactions": 6000000
      }
    }
  }
}

Cards

Card Resource Types​

Card Statuses​

Create Individual Debit Card​

Attributes​

Relationships​

Response​

201 Created​

Create Business Debit Card​

Attributes​

Relationships​

Response​

201 Created​

Create Business Credit Card​

Attributes​

Relationships​

Response​

201 Created​

Create Individual Virtual Debit Card​

Attributes​

Relationships​

Response​

201 Created​

Create Business Virtual Debit Card​

Attributes​

Relationships​

Response​

201 Created​

Create Business Virtual Credit Card​

Attributes​

Relationships​

Response​

201 Created​

Displaying Sensitive Card Data​

Integration steps​

Additional resources​

Activate Card​

Integration steps​

Additional resources​

Set PIN​

Integration steps​

Additional resources​

Get PIN Status​

Response​

200 OK​

Change PIN​

Integration steps​

Additional resources​

Report Stolen​

Response​

200 OK​

Report Lost​

Response​

200 OK​

Close Card​

Response​

200 OK​

Freeze Card​

Response​

200 OK​

Unfreeze Card​

Response​

200 OK​

Replace Card​

Attributes​

Response​

200 OK​

Get by Id​

Query Parameters​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update​

Update Individual Debit Card​

Update Business Debit Card​

Update Individual Virtual Debit Card​

Update Business Virtual Debit Card​

Card Resource Types

Card Statuses

Create Individual Debit Card

Attributes

Relationships

Response

201 Created

Create Business Debit Card

Attributes

Relationships

Response

201 Created

Create Business Credit Card

Attributes

Relationships

Response

201 Created

Create Individual Virtual Debit Card

Attributes

Relationships

Response

201 Created

Create Business Virtual Debit Card

Attributes

Relationships

Response

201 Created

Create Business Virtual Credit Card

Attributes

Relationships

Response

201 Created

Displaying Sensitive Card Data

Integration steps

Additional resources

Activate Card

Integration steps

Additional resources

Set PIN

Integration steps

Additional resources

Get PIN Status

Response

200 OK

Change PIN

Integration steps

Additional resources

Report Stolen

Response

200 OK

Report Lost

Response

200 OK

Close Card

Response

200 OK

Freeze Card

Response

200 OK

Unfreeze Card

Response

200 OK

Replace Card

Attributes

Response

200 OK

Get by Id

Query Parameters

Response

200 OK

List

Query Parameters

Response

200 OK

Update

Update Individual Debit Card

Update Business Debit Card

Update Individual Virtual Debit Card

Update Business Virtual Debit Card

Response