Card API

Retrieve, update, and delete credit card information for a given customer. New cards are created from tokens and can be added to new and existing customers.

Attributes

Name	Type	Description
object	string	The string `card`.
id	string	The card identifier matching `/card(_test)?_[0-9a-z]+/`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) card.
location	string	API path to retrieve the current `card` object.
bank	string	Card bank name. Note: derived from issuer identification number (IIN); may not be accurate.
brand	string	Card brand (e.g. Visa, Mastercard).
city	string	Billing address city.
country	string	Billing address country as two-letter ISO 3166 code. Note: if not supplied at token creation, value derived from issuer identification number (IIN) so may not be accurate.
created_at	string	UTC datetime of card creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
deleted	boolean	Whether card is deleted.
email	string	The email address of the customer
expiration_month	integer	Card expiration month (`M` or `MM`).
expiration_year	integer	Card expiration year (`YYYY`).
financing	string	Type of credit card financing. One of `credit`, `debit`, or `prepaid`. Note: derived from issuer identification number (IIN); may not be accurate.
fingerprint	string	Unique card-based fingerprint. Allows detection of identical cards.
first_digits	string	First six (6) digits of card number. Value will be present only for specific merchants based on additional security/business assessments.
last_digits	string	Last four (4) digits of card number.
name	string	Card owner name.
phone_number	string	Phone number.
postal_code	string	Card postal code.
security_code_check	boolean	Whether card passed pre-authorization. A card may fail pre-authorization for several reasons including, but not limited to, having an invalid `security_code`. As of 1 April 2020, this attribute only returns `true` regardless of the actual pre-authorization result.
state	string	Billing address state.
street1	string	Billing address street #1.
street2	string	Billing address street #2.
tokenization_method	string	The method by which a card is tokenized. The possible values are: `googlepay` (when tokenized by Google Pay `null` (when tokenized by Opn). This is the default value.

Example

JSON Response

{
  "object": "card",
  "id": "card_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards/card_test_no1t4tnemucod0e51mo",
  "deleted": false,
  "street1": "1448/4 Praditmanutham Road",
  "street2": null,
  "city": "Bangkok",
  "state": null,
  "phone_number": "0123456789",
  "postal_code": "10320",
  "country": "th",
  "financing": "credit",
  "bank": "Bank of the Unbanked",
  "brand": "Visa",
  "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
  "first_digits": null,
  "last_digits": "4242",
  "name": "Somchai Prasert",
  "expiration_month": 12,
  "expiration_year": 2024,
  "security_code_check": true,
  "tokenization_method": null,
  "created_at": "2019-12-31T12:59:59Z"
}

Destroy a card

- DELETE https://api.omise.co/customers/{id}/cards/{card_id}

Destroys the card matching :card_id belonging to customer matching :id.

Example

Destroy a card

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja/cards/card_test_5g021zls9ei5suyryss \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xsjvylia03ur542vn6');
$card = $customer->getCards()->retrieve('card_test_4xsjw0t21xaxnuzi9gs');
$card->destroy();

$card->isDestroyed(); # => true

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const card = omise.customers.destroyCard(
  'cust_test_no1t4tnemucod0e51mo',
  'card_test_no1t4tnemucod0e51mo',
);
console.log(card);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xsjvylia03ur542vn6")
card = customer.cards.retrieve("card_test_4xsjw0t21xaxnuzi9gs")
card.destroy

var customer = RetrieveCustomerWithCard();
var card = await Client.Customer(customer.Id).Cards.Destroy(customer.DefaultCard);
Console.WriteLine($"destroyed card: {card.Id} of customer {customer.Id}");

public void destroyCard() throws Exception {
    Request < Card > request =
        new Card.DeleteRequestBuilder(CUSTOMER_ID, CARD_ID)
        .build();
    Card card = client.sendRequest(request);

    System.out.printf("destroyed card: %s", card.getId());
}

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
card = customer.cards.retrieve("card_test_no1t4tnemucod0e51mo")
card.destroy()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Deletion{}
err := client.Do(result, &operations.DestroyCard{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
	CardID:     "card_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.destroy_card("cust_test_4xsjvylia03ur542vn6", "card_test_4xsjw0t21xaxnuzi9gs")

List cards

- GET https://api.omise.co/customers/{id}/cards

Returns a list of cards belonging to customer matching :id.

Request Parameters

Name	Type	Description
from	string	(optional, default: `1970-01-01T00:00:00Z`) Earliest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
limit	integer	(optional, default: `20`) Number of records returned.
offset	integer	(optional, default: `0`) Offset of the first record returned (i.e. how many records to skip from the beginning).
order	string	(optional, default: `chronological`, one of: `chronological`, `reverse_chronological`) Order of records returned.
to	string	(optional) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all cards

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja/cards \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4ybb9ymhoi7ju6wuizb');
$cards = $customer->getCards();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const card = await omise.customers.listCards('cust_test_no1t4tnemucod0e51mo');
console.log(card);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xsjvylia03ur542vn6")
cards = customer.cards

var customerId = "cust_test_566l662pnj240tgz61k";
var cards = await Client.Customer(customerId).Cards.GetList();
foreach (var card in cards)
{
    Console.WriteLine($"card: {card.Id} ({card.LastDigits})");
}

Request<ScopedList<Card>> request =
        new Card.ListRequestBuilder("cust_test_4xsjvylia03ur542vn6").build();
ScopedList<Card> cards = client().sendRequest(request);

System.out.printf("Total no. of cards: %d", cards.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
cards = customer.cards

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.CardList{}
err := client.Do(result, &operations.ListCards{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.list_cards("cust_test_4xsjvylia03ur542vn6")

Retrieve a card

- GET https://api.omise.co/customers/{id}/cards/{card_id}

Returns the card matching :card_id belonging to customer matching :id.

Example

Retrieve a card

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja/cards/card_test_5g021zls9ei5suyryss \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xsjvylia03ur542vn6');
$card = $customer->getCards()->retrieve('card_test_4xsjw0t21xaxnuzi9gs');

# Note that you can reload the card once you have an instance of one.
$card->reload();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const card = await omise.customers.retrieveCard(
  'cust_test_no1t4tnemucod0e51mo',
  'card_test_no1t4tnemucod0e51mo',
);
console.log(card);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xsjvylia03ur542vn6")
card = customer.cards.retrieve("card_test_4xsjw0t21xaxnuzi9gs")

# Note that you can reload the card once you have an instance of one.
card.reload

var customerId = "cust_test_566l662pnj240tgz61k";
var cardId = "card_test_566l661ty3h314lpl9e";
var card = await Client.Customer(customerId).Cards.Get(cardId);
Console.WriteLine($"last digits: {card.LastDigits}");

public void getCard() throws Exception {
    Request < Card > request = new Card.GetRequestBuilder(
        CUSTOMER_ID, CARD_ID).build();
    Card card = client.sendRequest(request);

    System.out.println("Card retrieved: " + card.getId());
}

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
card = customer.cards.retrieve("card_test_no1t4tnemucod0e51mo")

# Note that you can reload the card once you have an instance of one.
card.reload()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Card{}
err := client.Do(result, &operations.RetrieveCard{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
	CardID:     "card_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.retrieve_card("cust_test_4xsjvylia03ur542vn6", "card_test_4xsjw0t21xaxnuzi9gs")

Update a card

- PATCH https://api.omise.co/customers/{id}/cards/{card_id}

Updates the card matching :card_id belonging to customer matching :id.

Request Parameters

Name	Type	Description
city	string	(optional, but recommended) Billing address city. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
expiration_month	integer	(optional) Card expiration month (`M` or `MM`).
expiration_year	integer	(optional) Card expiration year (`YY` or `YYYY`).
name	string	(optional) Card owner name.
postal_code	string	(optional, but recommended) Card postal code. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.

Example

Update a card

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja/cards/card_test_5g021zls9ei5suyryss \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "expiration_month=12" \
  -d "expiration_year=2022" \
  -d "name=Somchai Prasert" \
  -d "postal_code=10310"

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xsjvylia03ur542vn6');
$card = $customer->getCards()->retrieve('card_test_4xsjw0t21xaxnuzi9gs');
$card->update(array(
  'expiration_month' => 11,
  'expiration_year' => 2017,
  'name' => 'Somchai Praset',
  'postal_code' => '10310'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const card = await omise.customers.updateCard(
  'cust_test_no1t4tnemucod0e51mo',
  'card_test_no1t4tnemucod0e51mo',
  {
    expiration_month: 11,
    expiration_year: 2028,
    name: 'John Doe',
    postal_code: 10310,
  },
);
console.log(card);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xsjvylia03ur542vn6")
card = customer.cards.retrieve("card_test_4xsjw0t21xaxnuzi9gs")
card.update({
  expiration_month: 11,
  expiration_year: 2017,
  name: "Somchai Praset",
  postal_code: "10310"
})

var customerId = "cust_test_566l662pnj240tgz61k";
var cardId = "card_test_566l661ty3h314lpl9e";
var card = await Client.Customer(customerId).Cards.Update(cardId, new UpdateCardRequest
{
    Name = "Somchai Prasert",
    ExpirationMonth = 8,
    ExpirationYear = 2022,
});

Console.WriteLine($"updated card name: {card.Id} ({card.Deleted})");

Request<Card> request =
        new Card.UpdateRequestBuilder("card_test_4xsjw0t21xaxnuzi9gs", "cust_test_4xsjvylia03ur542vn6")
                .expirationMonth(4)
                .expirationYear(2020)
                .name("John Doe")
                .postalCode("10101")
                .build();
Card card = client().sendRequest(request);

System.out.printf("Updated card: %s", card.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
card = customer.cards.retrieve("card_test_no1t4tnemucod0e51mo")
card.update(
    expiration_month=11,
    expiration_year=2022,
    name="Somchai Prasert",
    postal_code="10310",
)

# Or alternatively:
card.expiration_month = 11
card.expiration_year = 2022
card.name = "Somchai Prasert"
card.postal_code = "10310"
card.update()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Card{}
err := client.Do(result, &operations.UpdateCard{
	CustomerID:     "cust_test_no1t4tnemucod0e51mo",
	CardID:         "card_test_no1t4tnemucod0e51mo",
	City:           "Bangkok",
	ExpirationYear: 2026,
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.update_card("cust_test_4xsjvylia03ur542vn6", "card_test_4xsjw0t21xaxnuzi9gs", [
  expiration_month: 11,
  expiration_year: 2017,
  name: "Somchai Praset",
  postal_code: "10310",
])