EVevervault
Payments
Card Account Updates

Register a Card

Changed on

When registering a card, you can provide either an Evervault encrypted card number or a plaintext card number. If you provide a plaintext card number it will be encrypted and the encrypted value will be returned in the response.

Card registration is idempotent on card number. Registering the same card number a second time returns the existing Card object, rather than creating a new one. This means you can use the Card object id as a unique identifier. If you register an existing card number but with a different expiry date, the existing Card object is updated with the new date, and Evervault returns a 200 OK response. A 201 Created response indicates that a new Card object was created.

post/payments/cards

Request

Request body

numberstring required

The card number. This should be a valid Evervault encrypted card number or a valid plaintext card number.

externalCustomerReferencestring

An optional reference of your choice, such as a correlation ID, that is attached to the request. The reference will be visible in your logs. Must be between 1 and 255 characters.

Example request

{
  "number": "4242424242424242",
  "expiry": {
    "month": "12",
    "year": "29"
  },
  "externalCustomerReference": "00-4bf92f3577b34da6a3ce929d3e0e4736-00f067aa0ba902b7-01"
}

Response

Returns an existing Card object. If the card number is already registered but with a different expiry date, the date is updated to the value in the request before the Card object is returned.

idstring

The unique identifier for the card.

numberstring required

The Evervault encrypted card number. This can be decrypted using Relay decryption or using a function.

binstring required

The first 6 or 8 digits of the card number.

lastFourstring required

The last 4 digits of the card number.

brand'visa' | 'mastercard' | 'american-express' | 'discover' | 'diners-club' | 'jcb' | 'unionpay'

The card brand associated with the payment card.

funding'debit' | 'credit' | 'prepaid' | 'deferred-debit' | 'charge'

The card funding type specifies the method by which transactions are financed.

segment'consumer' | 'commercial' | 'business' | 'government' | 'payouts' | 'all'

The card segment indicates the primary market or usage category of the card.

countrystring iso-3166-1-alpha-2

The country where the card was issued.

currencystring iso-4217-alphabetic

The currency of the card.

issuerstring

The name of the card issuer.

status'active' | 'replaced' | 'closed' | 'invalid'

The current status of the card.

replacementstring nullable

The ID of the replacement card. This field is only present if the card has been replaced.

automaticUpdates'enabled' | 'issuer-not-enrolled' | 'disabled'

The status of Card Account Updater on this card. Evervault currently supports Card Account Updates for Visa, Mastercard and American Express cards.

createdAtinteger required

The Unix timestamp of when the card was created.

updatedAtinteger nullable

The Unix timestamp of when the card was last updated.

Example response

{
  "id": "card_eead1d640d7c",
  "number": "ev:debug:Tk9D:number:nTepvAI585M7lUVp:AkJ6Brzat0E7ui8DSKCSXO7AopU/+GFuBekQ6cGx7eTl:sfihK53itmHp+URxomnTITUpwQwM5nnRrnQ0qdIOUlA=:$",
  "expiry": {
    "month": "9",
    "year": "26"
  },
  "bin": "424242",
  "lastFour": "4242",
  "brand": "visa",
  "funding": "credit",
  "segment": "consumer",
  "country": "gb",
  "currency": "gbp",
  "issuer": "Gringotts Wizarding Bank and Trust Company",
  "status": "active",
  "replacement": null,
  "automaticUpdates": "enabled",
  "createdAt": 169297262323,
  "updatedAt": null
}

Changes

  • 8d0ca833fa04Revision changes
    • info

      added the new optional request property

    • info

      removed the cardholder-opted-out enum value from the response property for the response status

    • info

      removed the cardholder-opted-out enum value from the response property for the response status

  • 5e1eb58d42d5Revision changes
    • info

      the response's property pattern ^[a-z]{2}$ was removed for the status

    • info

      the response's property pattern ^[a-z]{2}$ was removed for the status

    • info

      the response's property pattern ^[a-z]{3}$ was removed for the status

    • info

      the response's property pattern ^[a-z]{3}$ was removed for the status