Create Card on File

POST /accounts/:customerAccountId/paymentOptions/

This methods allows the storing of card details that have already been authenticated and is used to tokenize and store a customer's card for future use. Prior to calling this endpoint, the card must be authenticated through a 3DS session using purpose: ADD_CARD, and sensitive card data must be sent via PCI forwarding to /forwarding/tokenize.

The returned storedPaymentOptionReference can be used, for example, in /payment/mit endpoint to authorize a merchant-initiated payment without the need of additional 3DS challenges or submission of card details.

important

This endpoint contains PCI data and requires forwarding through /forwarding/tokenize.

Request

Path Parameters

customerAccountId stringrequired

Possible values: <= 255 characters

Unique identifier of the customer account.

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

Authorization stringrequired

Basic M2lwN2Yx...OGU3Mg==

X-Pcp-Url stringrequired

{baseUrl}/accounts/{customerAccountId}/paymentOptions

X-Pcp-Authorization stringrequired

{{pci_base64_public_private}}

X-Pcp-Cc-Path stringrequired

cardDetails.cardToken

application/json

Body

required

paymentOption

object

required

card

object

required

3DS

object

required

3DS2

object

acsEci stringrequired

Possible values: >= 2 characters and <= 2 characters

Indicates the security level of the transaction.

acsTransactionId stringrequired

Possible values: <= 100 characters

A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction.

authenticationToken stringrequired

Possible values: >= 28 characters and <= 32 characters

A unique identifier for the 3-D Secure authentication transaction.

dsTransactionId stringrequired

Possible values: <= 100 characters

A unique transaction identifier assigned by the scheme Directory Server to identify the 3DS transaction.

protocolVersion stringrequired

Possible values: <= 6 characters

The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo.

transactionStatus stringrequired

Possible values: non-empty and <= 1 characters, [N, Y, C, R, U, A]

Indicates the result of payer authentication with the issuer. Possible values:

N - Transaction did not qualify as an authenticated transaction or account verification.
Y - The transaction qualified as an authenticated transaction.
C - 3DS version 2.2.0 only. Transaction requires a challenge.
R - 3DS version 2.2.0 only. A challenge is recommended for the transaction.
U - 3DS version 2.2.0 only. The transaction is unavailable for authentication.
A - 3DS version 2.2.0 only. The transaction is authenticated with a frictionless flow.

cardDetails

object

required

cvvToken stringrequired

Possible values: <= 18 characters

CVV token

cardBrand stringrequired

Possible values: <= 16 characters, [AMEX, APPLPAY, BACSDD, BNKACCT, CRTBANCAIR, DISCOVER, GGLPAY, GIROPAY, IDEAL, JCB, MSTRCRD, MSTRO, PAYBBNK, PAYPAL, PAYU, PAYUBLK, PAYUTWST, PAYUINST, PREPMNT, SEPADDB2B, SEPADDCORE, VISA, VISADBIT]

Card brand code. Please refer to Data Model.

cardExpiryMonth stringrequired

Possible values: >= 2 characters and <= 2 characters

Credit card expiration month in format "MM".

cardExpiryYear stringrequired

Possible values: >= 2 characters and <= 4 characters

Credit card expiration year in format "YY" or "YYYY"

network-tokens string

Possible values: <= 100 characters

Card holder's name as displayed on the card

cardToken stringrequired

Possible values: <= 18 characters

PAN token

billingAddress

object

required

Consumer's billing address data. See Address in Data model.

addressLine1 stringrequired

Possible values: <= 60 characters

Street name.

addressLine2 string

Possible values: <= 60 characters

Apartment, suite, unit, building, floor or other secondary address information.

addressLine3 string

Possible values: <= 60 characters

Specific delivery instructions, department names, or additional floor information.

city stringrequired

Possible values: <= 50 characters

The city or localitly of the address.

countryCode stringrequired

Possible values: >= 3 characters and <= 3 characters

ISO-3 code of the address country (e.g., DEU for Germany).

number string

Possible values: <= 10 characters

The house or building number corresponding to the street address.

postCode stringrequired

Possible values: <= 10 characters

The postal or ZIP code of the address.

state string

Possible values: <= 3 characters

3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

businessConsumer

object

nullable

Company data, in case the consumer is a business or a legal entity.
Mandatory, unless consumer is provided.
consumer and businessConsumer objects may not be submitted together.

companyName stringrequired

Possible values: <= 100 characters

Name of the legal entity

companyRegistrationCountryCode string

Possible values: >= 2 characters and <= 3 characters

Company registration country ISO2 or ISO3 code

companyRegistrationNumber string

Possible values: <= 50 characters

Company registration number

companyType stringrequired

Possible values: <= 100 characters

culture string

Possible values: <= 5 characters

Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

emailAddress stringrequired

Possible values: <= 255 characters

Customer email address for any notification

taxId string

Possible values: <= 30 characters

Person's tax identification number

consumer

object

nullable

Consumer's personal data, in case the consumer is a physical person.
Mandatory, unless businessConsumer is provided.
consumer and businessConsumer objects may not be submitted together.

culture string

Possible values: <= 5 characters

dateOfBirth date

Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$

Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01

emailAddress emailrequired

Possible values: <= 255 characters

Customer email address for any notification

firstName stringrequired

Possible values: <= 60 characters

Person first name

gender string

Possible values: <= 6 characters

Person gender

homePhone string

Possible values: <= 30 characters

Person's home phone number (including the country code)

lastName stringrequired

Possible values: <= 60 characters

Person last name

merchantCustomerId string

Possible values: <= 255 characters

Consumer/Customer Account Id in the merchant system. When provided into the Create Checkout API, SmartPay will request e-wallet account creation which will have external account reference equals to the given merchantCustomerId value.

middleName string

Possible values: <= 60 characters

The customer's middle name

mobilePhone string

Possible values: <= 30 characters

Person's mobile phone number (including the country code)

taxId string

Possible values: <= 30 characters

Person's tax identification number

timezone string

Possible values: <= 50 characters

Preferred timezone name

title string

Possible values: <= 3 characters

Person title

workPhone string

Possible values: <= 30 characters

Person's work phone number (including the country code)

criteria

object[]

nullable

List of custom key-value pairs that the merchant can submit.
The names callBackUrl and redirectUrl will be disregarded.
For transactions using Apple Pay or Google Pay™, please consult the respective integration pages for details on required domain configuration and button styling parameters within this object.

Array [

name stringrequired

Possible values: <= 50 characters

name of the parameter. The value must be unique within the criteria array

value stringrequired

Possible values: <= 100 characters

value of the parameter

]

customReferences

object

nullable

For external party usage. Please refer to Data Model for more details.

custom1 string

Possible values: <= 255 characters

generic custom reference

custom2 string

Possible values: <= 255 characters

generic custom reference

custom3 string

Possible values: <= 255 characters

generic custom reference

customerAccountId stringnullable

Possible values: <= 255 characters

Consumer's account identifier in the merchant's system. To be used as an external account reference. Disregarded when provided as a path parameter.

extraInfo

object

nullable

Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.

customerGroup string

Possible values: <= 100 characters

In case customer group rule is defined in channel configuration, this value is used for channel evaluation

productGroup string

Possible values: <= 100 characters

In case customer group rule is defined in channel configuration, this value is used for channel evaluation

payment

object

required

The payment amount to be charged against the payment option.

amount decimalrequired

Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

Transaction modification amount

currencyCode stringrequired

Possible values: >= 3 characters and <= 3 characters

Transaction modification currency. The 3-letter currency ISO-4217 code

description stringrequired

Possible values: <= 127 characters

A terse description of the good or service being sold i.e., the reason for the payment

shopCountry stringnullable

Possible values: <= 2 characters

The ISO 3166-1 alpha-2 code of the shop country. Must match at least one of the countries configured for the merchant.

Responses

Card successfully stored

application/json

Schema
Example (from schema)
Example

Schema

storedPaymentOptionReference stringrequired

Possible values: <= 100 characters

Reference to the created stored payment option.

cardDetails

object

required

cvvToken stringrequired

Possible values: <= 18 characters

CVV token

cardBrand stringrequired

Card brand code. Please refer to Data Model.

cardExpiryMonth stringrequired

Possible values: >= 2 characters and <= 2 characters

Credit card expiration month in format "MM".

cardExpiryYear stringrequired

Possible values: >= 2 characters and <= 4 characters

Credit card expiration year in format "YY" or "YYYY"

network-tokens string

Possible values: <= 100 characters

Card holder's name as displayed on the card

cardToken stringrequired

Possible values: <= 18 characters

PAN token

{
  "storedPaymentOptionReference": "string",
  "cardDetails": {
    "cardBrand": "AMEX",
    "cardExpiryMonth": "09",
    "cardExpiryYear": "2029",
    "network-tokens": "JOHN DOE",
    "cardToken": "LLVOXVAJINJWPDDPZA"
  }
}

{
  "storedPaymentOptionReference": "Ky28Mgp5GLauHPmYxUnZO",
  "cardDetails": {
    "cardBrand": "MSTRCRD",
    "cardHolder": "JOHN DOE",
    "cardToken": "512345PFITLJFS0008",
    "cvvToken": "WNZSWCUMAAHIDDVUDC",
    "cardExpiryMonth": "09",
    "cardExpiryYear": "2029"
  }
}

Bad Request

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

Forbidden

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

Not Found

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}

Create Card on File

/accounts/:customerAccountId/paymentOptions/

Request​

Path Parameters

Header Parameters

Body

Responses​

Request

Responses