The /credit_card API calls

The credit_card object represents a user’s credit card and can be used to tokenize credit cards. Use the following calls to create, view, and modify credit_card objects on WePay:

Warning

While WePay CC Tokenization API greatly reduces the scope of PCI Compliance and increases your security, your application is still required to be compliant with the Payment Card Industry Data Security Standards (PCI-DSS) and the Payment Application Data Security Standards (PA-DSS) whenever applicable. If you want to minimize the scope of your PCI compliance, we recommend that you use our iframe checkout. Use of the credit card tokenization feature requires special approval from WePay. Please apply for approval on your application’s dashboard.

For more information about PCI standards and compliance, see the following link: https://www.pcisecuritystandards.org/.

Credit Card States

The credit_card object has the following states and possible state transitions:

new The credit card was just created by the application.
authorized The credit card was authorized either with an immediate charge or the /credit_card/authorize call. You can use the credit_card_id to charge this card in the future.
expired The credit card was created but you did not charge the card or call /credit_card/authorize within 30 minutes.
deleted The credit card was deleted or there was a failed credit card authorization attempt.
invalid You tried to charge the card but the response we received indicated that the card is completely invalid and can never be charged (e.g., AVS mismatch, also known as a billing address check failure).

Credit Card State Diagram

Version: v2 2016-08-10

POST Endpoint

https://wepayapi.com/v2/credit_card

/credit_card

Use this call to lookup the details of a credit card that you have tokenized.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your application's dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your application's dashboard.
credit_card_id Yes Integer (64 bits) The unique ID of the credit card you want to look up.

Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id": 235810395803
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of a credit card.
credit_card_name String (255 chars) The string that identifies a credit card, such as MasterCard xxxxxx4769.
state String (255 chars) The state that the credit card is in.
user_name String (255 chars) The name on the card (e.g., Bob Smith).
email String (255 chars) The email address of the user who owns the card.
create_time Integer (64 bits) The Unix time when the credit card was created.
input_source String (255 chars) The input source of the credit card.

Possible values are card_keyed, card_swiped, card_transfer, card_emv, card_fallback_swipe, card_fallback_keyed, and card_recurring
virtual_terminal_mode String (255 chars) The virtual terminal mode of the credit card.

Possible values are mobile, web, none.
reference_id String (255 chars) The unique ID for the credit card.
expiration_month Integer (32 bits) The expiration month on the credit card.

Possible values: integers between 1 and 12.
expiration_year Integer (32 bits) The expiration year on the credit card.
last_four String (4 chars) The last four digits of the credit card number.

Example

{
  "credit_card_id": 235810395803,
  "credit_card_name": "MasterCard xxxxxx4769",
  "state": "new",
  "user_name": "Bob Smith",
  "email": "bob.smith@example.com",
  "create_time": 1367958263,
  "input_source": "card_keyed",
  "virtual_terminal_mode": "none",
  "reference_id": "123abc",
  "expiration_month": 4,
  "expiration_year": 2020,
  "last_four": "4769"
}

/credit_card/create

This call allows you to pass credit card information and receive back a credit_card_id. You will then be able to use that credit_card_id on the /checkout/create call to execute a payment immediately with that credit card. Note that you will need to call the /checkout/create call or the /credit_card/authorize call within 30 minutes or the credit_card object will expire. The credit card created by the /credit_card/create call is tokenized and the card details are immutable.

Tip

If you pass an access_token on this call, the credit card will be added to the user associated with that access_token. If you want to do a guest payment (ie the payer is not registered on WePay), then do not pass an access_token.

Tip

User contact information (especially e-mail) is key for risk analysis, so please make sure you provide the actual end-user contact information.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
cc_number Yes String (255 chars) The number on the credit card.
cvv Yes Integer (32 bits) The CVV (also known as a card security code, CVV2, or CVC) on the card.
expiration_month Yes Integer (32 bits) The expiration month on the credit card.
expiration_year Yes Integer (32 bits) The expiration year on the credit card.
user_name Yes String (255 chars) The full name of the user that the card belongs to.
email Yes String (255 chars) Valid email address of the user the card belongs to. If the e-mail belongs to the merchant, your application's user account, or is invalid, the transaction may be canceled for risk reasons.
address Yes Address Structure The billing address on the card (a valid JSON object, not a JSON serialized string). Only postal_code and country are required.
original_ip No String (16 chars) The IP address of the user to whom this card belongs. This should be sent if you are not using WePay's Javascript library.
original_device No String (255 chars) The user-agent (for web) or the IMEI (for mobile) of the user to whom his card belongs. This should be sent if you are not using WePay's Javascript library.
reference_id No String (255 chars) The unique reference ID of the credit_card.
auto_update

No Boolean Automatically update credit cards that have been stored with WePay. If a card is expired, or has been replaced (e.g., due to theft), it will be automatically updated based in information provided by card networks.
callback_uri No String (2083 chars) The URI that will receive IPNs for this credit card. You will receive an IPN whenever the card information is updated.
virtual_terminal

No Enum This is set if the merchant has manually entered the credit card number.

Possible values: web and mobile.

Example

{
   "client_id": 187493,
   "user_name": "Bob Smith",
   "email": "test@example.com",
   "cc_number": "5496198584584769",
   "cvv": "123",
   "expiration_month": 4,
   "expiration_year": 2020,
   "address": {
      "country": "US",
      "postal_code": "94025"
   }
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of the credit card.
state String (255 chars) The state that the credit card is in.

Example

{
  "credit_card_id": 235810395803,
  "state": "new"
}

/credit_card/authorize

You should only use this call if you are not going to immediately make the /checkout/create call with the credit_card_id.

This call authorizes the card and allows you use it at a later time or date (for crowdfunding, subscriptions, etc.). If you don’t call /credit_card/authorize or /checkout/create within 30 minutes, the credit_card object will expire.

This call returns the same response as the /credit_card call.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your application dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your application dashboard.
credit_card_id Yes Integer (64 bits) The unique ID of the credit card you want to authorize.

Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id": 235810395803
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of a credit card.
credit_card_name String (255 chars) The string that identifies a credit card, such as MasterCard xxxxxx4769.
state String (255 chars) The state that the credit card is in.
user_name String (255 chars) The name on the card (e.g., Bob Smith).
email String (255 chars) The email address of the user who owns the card.
create_time Integer (64 bits) The Unix time when the credit card was created.
input_source String (255 chars) The input source of the credit card.

Possible values are card_keyed, card_swiped, card_transfer, card_emv, card_fallback_swipe, card_fallback_keyed, and card_recurring
virtual_terminal_mode String (255 chars) The virtual terminal mode of the credit card.

Possible values are mobile, web, none.
reference_id String (255 chars) The unique ID for the credit card.
expiration_month Integer (32 bits) The expiration month on the credit card.

Possible values: integers between 1 and 12.
expiration_year Integer (32 bits) The expiration year on the credit card.
last_four String (4 chars) The last four digits of the credit card number.

Example

{
  "credit_card_id": 235810395803,
  "credit_card_name": "MasterCard xxxxxx4769",
  "state": "new",
  "user_name": "Bob Smith",
  "email": "bob.smith@example.com",
  "create_time": 1367958263,
  "input_source": "card_keyed",
  "virtual_terminal_mode": "none",
  "reference_id": "123abc"
}

/credit_card/find

Use this call to search through tokenized credit cards. The response is an array of credit cards matching the search parameters. Each element of the array will include the same data as returned from the /credit_card call.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your app dashboard.
reference_id No String (255 chars) The reference ID of the credit card you want to find.
limit No Integer (64 bits) The maximum number of results you want returned.

Default: 50
start No Integer (64 bits) The start position for your search.

Default: 0
sort_order No String (255 chars) Sort the results of the search by time created. Use desc for most recent to least recent. Use asc for least recent to most recent.

Default: desc

Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "reference_id": "abc123"
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of a credit card.
credit_card_name String (255 chars) The string that identifies a credit card, such as MasterCard xxxxxx4769.
state String (255 chars) The state that the credit card is in.
user_name String (255 chars) The name on the card (e.g., Bob Smith).
email String (255 chars) The email address of the user who owns the card.
create_time Integer (64 bits) The Unix time when the credit card was created.
input_source String (255 chars) The input source of the credit card.

Possible values are card_keyed, card_swiped, card_transfer, card_emv, card_fallback_swipe, card_fallback_keyed, and card_recurring
virtual_terminal_mode String (255 chars) The virtual terminal mode of the credit card.

Possible values are mobile, web, none.
reference_id String (255 chars) The unique ID for the credit card.
expiration_month Integer (32 bits) The expiration month on the credit card.

Possible values: integers between 1 and 12.
expiration_year Integer (32 bits) The expiration year on the credit card.
last_four String (4 chars) The last four digits of the credit card number.
[
   {
      "credit_card_id": 235810395803,
      "credit_card_name": "MasterCard xxxxxx4769",
      "state": "new",
      "user_name": "Bob Smith",
      "email": "bob.smith@example.com",
      "create_time": 1367958263,
      "input_source": "card_keyed",
      "virtual_terminal_mode": "none",
      "reference_id": "123abc",
      "expiration_month": 4,
      "expiration_year": 2020,
      "last_four": "4769",
      "auto_update": false
   },
   {
      "credit_card_id": 235810395803,
      "credit_card_name": "Visa xxxxxx0002",
      "state": "new",
      "user_name": "Jane Smith",
      "email": "jane.smith@example.com",
      "create_time": 1367954124,
      "input_source": "card_keyed",
      "virtual_terminal_mode": "none",
      "reference_id": "124abd",
      "expiration_month": 5,
      "expiration_year": 2025,
      "last_four": "0002",
      "auto_update": true
   }
]

/credit_card/modify

Use this call to make modifications to an existing tokenized credit card. The response for this call is the same as from the /credit_card call.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your app dashboard.
credit_card_id Yes Integer (64 bits) The unique ID of the credit card you want to authorize.
auto_update

No Boolean Automatically update credit cards that have been stored with WePay. If a card is expired, or has been replaced (e.g. due to theft), it is automatically updated based on information provided by the card network.
callback_uri No String (2083 chars) The URI that receives IPNs for this credit card. You receive an IPN whenever the card information is updated.

Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id":"1234567",
  "auto_update": true,
  "callback_uri": "http://www.example.com/ipn"
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of a credit card.
credit_card_name String (255 chars) The string that identifies a credit card, such as MasterCard xxxxxx4769.
state String (255 chars) The state that the credit card is in.
user_name String (255 chars) The name on the card (e.g., Bob Smith).
email String (255 chars) The email address of the user who owns the card.
create_time Integer (64 bits) The Unix time when the credit card was created.
input_source String (255 chars) The input source of the credit card.

Possible values are card_keyed, card_swiped, card_transfer, card_emv, card_fallback_swipe, card_fallback_keyed, and card_recurring
virtual_terminal_mode String (255 chars) The virtual terminal mode of the credit card.

Possible values are mobile, web, none.
reference_id String (255 chars) The unique ID for the credit card.
expiration_month Integer (32 bits) The expiration month on the credit card.

Possible values: integers between 1 and 12.
expiration_year Integer (32 bits) The expiration year on the credit card.
last_four String (4 chars) The last four digits of the credit card number.

Example

{
  "credit_card_id": 235810395803,
  "credit_card_name": "MasterCard xxxxxx4769",
  "state": "new",
  "user_name": "Bob Smith",
  "email": "bob.smith@example.com",
  "create_time": 1367958263,
  "input_source": "card_keyed",
  "virtual_terminal_mode": "none",
  "reference_id": "123abc",
  "expiration_month": 4,
  "expiration_year": 2020,
  "last_four": "4769"
}

/credit_card/transfer

This call is similar to /credit_card/create. It is intended to be used server-server for the purpose of migrating credit card information to WePay. If auto_authorize is set to true, WePay will automatically test cards transferred to us via /credit_card/transfer by making a $0.00 authorization (in rare instances, the authorization amount may be $1.00 instead). All payment error codes (200X) are possible return values for /credit_card/transfer.

Tip

This call requires permission from WePay. Once given, it must be used only for the original purpose covered when permission was given.

  1. If migrating a batch of users, an end date is normally expected, after which permission for this call will be removed.
  2. It is not necessary to follow this call with /credit_card/authorize. The transferred cards will automatically be authorized if valid and if auto_authorize is set to true.
  3. Access tokens are not sent. Cards transferred are automatically available for use by any merchant on the platform (as identified by the client ID).

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your app dashboard.
cc_number Yes String (255 chars) The number on the credit card.
expiration_month Yes Integer (32 bits) The expiration month of the credit card.
expiration_year Yes Integer (32 bits) The expiration year of the credit card.
user_name Yes String (255 chars) The full name of the user to whom the card belongs.
email Yes String (255 chars) The email address of the user to whom the card belongs.
address Yes Address Structure The billing address on the card (a valid JSON object, not a JSON serialized string). Only postal_code and country are required.
reference_id No String (255 chars) The unique reference ID of the credit card.
auto_authorize No Boolean The parameter that indicates whether to make a $0 authorization on the credit card being transferred.

Default: false

Example

{
   "client_id": 12345,
   "client_secret": "my_client_secret",
   "cc_number": "12345678910",
   "expiration_month": 1,
   "expiration_year": 2025,
   "user_name": "John Doe",
   "email": "john.doe@example.com",
   "address": {
      "postal_code": "97477",
      "country": "US"
   }
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of the credit card.
state String (255 chars) The state that the credit card is in.

Example

{
   "credit_card_id": 12345,
   "state": "authorized"
}

/credit_card/delete

Delete the credit card when you don’t need it anymore.

Tip

Once a credit card is deleted the card will no longer be available to make payments.

Warning

Do not delete a credit card before the state of the /checkout is captured.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your app dashboard.
credit_card_id Yes Integer (64 bits) The unique ID of the credit card you want to delete.

Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id": 235810395803
}

Response

Response Type Description
credit_card_id Integer (64 bits) The unique ID of the credit card.
state String (255 chars) The current state of the credit card.

Example

{
  "credit_card_id": 235810395803,
  "state": "deleted"
}

/credit_card/enable_recurring

Enable an EMV card to make recurring payments.

Warning

If you intend to make a charge on the physically present card, do not call /credit_card/enable_recurring until after the original /checkout/create call has been made successfully against the card present checkout.

Arguments

Parameter Required Type Description
client_id Yes Integer (64 bits) The ID for your API application. You can find it on your app dashboard.
client_secret Yes String (255 chars) The secret for your API application. You can find it on your app dashboard.
credit_card_id Yes String (255 chars) The unique ID of the credit card.
address Yes Address Structure The billing address on the card (a valid JSON object, not a JSON serialized string).

Example

{
   "client_id": 12345,
   "client_secret": "abcd1234",
   "credit_card_id": "235810395803",
   "address": {
      "address1": "100 Main Street",
      "address2": "Apt #34",
      "city": "Redwood City",
      "state": "CA",
      "country": "US",
      "postal_code": "94059"
   }
}

Response

Response Type Description
credit_card_id String (255 chars) The unique ID of the credit card.

Example

{
  "credit_card_id": "235810395803"
}