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 in conjunction with WePay’s Tokenization JavaScript to create, view, and modify credit_card objects on WePay:

• /credit_card
• /credit_card/create
• /credit_card/authorize
• /credit_card/find
• /credit_card/modify
• /credit_card/transfer
• /credit_card/delete
• /credit_card/enable_recurring

Warning

While the WePay credit card Tokenization API and Javascript 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/.

Note

If a credit card is stored but goes without payment activity for 3 or more years, then the credit card data will be deleted.

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).

Version: v2 2019-04-03

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 timestamp (UTC) 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, card_recurring, and apple_pay.
virtual_terminal_mode	String (255 chars)	The virtual terminal mode of the credit card. Possible values are mobile, web and null.
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.
bin	String (6 chars)	Bank identification number. The initial six digits of a credit card number. null is returned if BIN is not available. When the input_source is apple_pay, BIN is a virtual value and should not be considered as the actual BIN number.
last_four	String (4 chars)	The last four digits of the credit card number.
backing_instrument_name	String (255 chars)	The backing instrument for the credit card such as Visa 2149. Value exists for digital wallet payments, null otherwise.
card_on_file	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

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": null,
    "reference_id": "123abc",
    "expiration_month": 4,
    "expiration_year": 2020,
    "bin": "547456",
    "last_four": "4769",
    "backing_instrument_name": null,
    "card_on_file": false,
    "recurring": false
}

/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.

Permission Required

‘cvv’ is optional only if the app has the correct permissions. Please speak to your account manager for more 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.
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.
address	Yes	Address Structure	The billing address on the card (a valid JSON object, not a JSON serialized string). Only postal_code is required (and US is assumed if country is not provided).
user_name	No	String (255 chars)	The full name of the user that the card belongs to. Note: Cards which will require SCA must contain the card holder's first and last name such that the value has a space between strings: "first_name last_name" This parameter is only optional when the app has the correct permissions.
email	No	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. This parameter is only optional when the app has the correct permissions.
cvv	No	String	The CVV (also known as a card security code, CVV2, or CVC) on the card. This parameter is only optional when the app has the correct permissions.
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 on information provided by card networks. To receive these updates, be sure to set a callback_uri.
callback_uri	No (unless using auto_update)	String (2083 chars)	The URI that will receive IPNs for this credit card. You will receive an IPN whenever the card information is updated. Note: Your platform may test using ports in staging but ports are not allowed in production.
virtual_terminal_mode	No	Enum	This is set if the merchant has manually entered the credit card number. Possible values: mobile, web and null.
payment_request_flag	No	Boolean	This is set if the credit card was obtained using the W3C Payment Request API.
card_on_file	No	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	No	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

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"
    },
    "card_on_file": false,
    "recurring": false
}

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 by calling a $0 authorization 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.
account_id	No	Integer (64 bits)	The unique ID of the account that will be associated with transactions made with the credit card. If specified, the account name will be part of the soft descriptor in the payer's bank statement.
strong_customer_authentication	No	Object	Only required for credit cards with a UK address and either Visa or MasterCard brand. WePay recommends that any platform which supports UK merchants to implement this parameter on all /credit_card/authorize requests. Provide information allowing payers to authenticate the auth with their card issuer. Find more information on strong customer authentication here.

Example

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

GBP Example

{
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id": 235810395803,
  "strong_customer_authentication": {
    "redirect_uri": "https://www.example.com",
    "challenge_mode": "iframe",
    "device_information": {
      "browser": {
        "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
        "challenge_iframe_size": "FULL_SCREEN",
        "accept_headers": "application/json",
        "color_depth": 48,
        "java_enabled": true,
        "language": "en-US",
        "screen_height": 400,
        "screen_width": 250,
        "time_zone": 0
      },
      "ip_address": "12.37.161.213"
    }
  }  
}

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 timestamp (UTC) 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, card_recurring, and apple_pay.
virtual_terminal_mode	String (255 chars)	The virtual terminal mode of the credit card. Possible values are mobile, web and null.
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.
bin	String (6 chars)	Bank identification number. The initial six digits of a credit card number. null is returned if BIN is not available. When the input_source is apple_pay, BIN is a virtual value and should not be considered as the actual BIN number.
last_four	String (4 chars)	The last four digits of the credit card number.
backing_instrument_name	String (255 chars)	The backing instrument for the credit card such as Visa 2149. Value exists for digital wallet payments, null otherwise.
card_on_file	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

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": null,
    "reference_id": "123abc",
    "expiration_month": 4,
    "expiration_year": 2020,
    "bin": "547456",
    "last_four": "4769",
    "auto_update": false,
    "backing_instrument_name": null,
    "card_on_file": false,
    "recurring": false
}

/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 timestamp (UTC) 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, card_recurring, and apple_pay.
virtual_terminal_mode	String (255 chars)	The virtual terminal mode of the credit card. Possible values are mobile, web and null.
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.
bin	String (6 chars)	Bank identification number. The initial six digits of a credit card number. null is returned if BIN is not available. When the input_source is apple_pay, BIN is a virtual value and should not be considered as the actual BIN number.
last_four	String (4 chars)	The last four digits of the credit card number.
backing_instrument_name	String (255 chars)	The backing instrument for the credit card such as Visa 2149. Value exists for digital wallet payments, null otherwise.
card_on_file	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

[
    {
        "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": null,
        "reference_id": "123abc",
        "expiration_month": 4,
        "expiration_year": 2020,
        "bin": "547456",
        "last_four": "4769",
        "auto_update": false,
        "backing_instrument_name": null,
        "card_on_file": false,
        "recurring": false
    },
    {
        "credit_card_id": 240957365930,
        "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": null,
        "reference_id": "124abd",
        "expiration_month": 5,
        "expiration_year": 2025,
        "bin": "123456",
        "last_four": "0002",
        "auto_update": true,
        "backing_instrument_name": null,
        "card_on_file": false,
        "recurring": false
    }
]

/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. To receive these updates, be sure to set a callback_uri.
callback_uri	No (unless using auto_update)	String (2083 chars)	The URI that receives IPNs for this credit card. You receive an IPN whenever the card information is updated. Note: Your platform may test using ports in staging but ports are not allowed in production.
card_on_file	No	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	No	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

Example

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

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 timestamp (UTC) 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, card_recurring, and apple_pay.
virtual_terminal_mode	String (255 chars)	The virtual terminal mode of the credit card. Possible values are mobile, web and null.
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.
bin	String (6 chars)	Bank identification number. The initial six digits of a credit card number. null is returned if BIN is not available. When the input_source is apple_pay, BIN is a virtual value and should not be considered as the actual BIN number.
last_four	String (4 chars)	The last four digits of the credit card number.
backing_instrument_name	String (255 chars)	The backing instrument for the credit card such as Visa 2149. Value exists for digital wallet payments, null otherwise.
card_on_file	Boolean	Indicates if the resulting token will be kept on file as a non-recurring payment method.
recurring	Boolean	Indicates if the resulting token will be kept on file as a recurring payment method.

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": null,
    "reference_id": "123abc",
    "expiration_month": 4,
    "expiration_year": 2020,
    "bin": "547456",
    "last_four": "4769",
    "backing_instrument_name": null,
    "card_on_file": false,
    "recurring": false
}

/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). Only postal_code and country are required.

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"
}