Store Payment Option

POST 
/accounts/:customerAccountId/paymentOptions

This methods allows the storing of card details that have already been authenticated. 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

Customer identifier

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

application/json

Body

required

paymentOption

object

required

Details of the payment option to be stored.

card

object

required

Card details including 3DS data and card metadata.

3DS

object

3D Secure data for the card.

3DS2

object

3DS version 2 specific authentication data.

acsEci stringrequired

Possible values: <= 2 characters

Electronic Commerce Indicator from ACS (e.g., '02').

acsTransactionId uuidrequired

Transaction ID assigned by ACS.

authenticationToken stringrequired

Possible values: <= 64 characters

Token issued after successful 3DS authentication.

dsTransactionId uuidrequired

Transaction ID from the Directory Server.

protocolVersion stringrequired

Possible values: <= 10 characters

3DS protocol version used during authentication.

transactionStatus stringrequired

Possible values: <= 1 characters, [Y, N, U, A, R]

Possible statuses:
Y = Authenticated,
N = Not Authenticated,
U = Unavailable,
A = Attempted,
R = Rejected.

cardDetails

object

required

Masked card data for the payment method.

cardBrand stringrequired

Possible values: <= 16 characters

Brand of the card (e.g., VISA, MASTERCARD).

cardExpiryMonth stringrequired

Possible values: Value must match regular expression ^(0[1-9]|1[0-2])$

Expiration month of the card in MM format.

cardExpiryYear stringrequired

Possible values: Value must match regular expression ^20\d{2}$

Expiration year of the card in YYYY format.

cardHolder stringrequired

Possible values: <= 64 characters

Full name of the cardholder.

cardToken stringrequired

Possible values: <= 32 characters

Tokenized identifier of the card.

billingAddress

object

required

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

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

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

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.

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[]

List of name/value pair custom parameters.

Array [

name stringrequired

Possible values: <= 64 characters

Name of the custom parameter.

value stringrequired

Possible values: <= 256 characters

Value of the custom parameter.

]

customReferences

object

Optional custom reference fields used for merchant tracking.

custom1 string

Possible values: <= 255 characters

custom2 string

Possible values: <= 255 characters

custom3 string

Possible values: <= 255 characters

customerAccountId string

Possible values: <= 255 characters

Unique external identifier of the customer account.

extraInfo

object

Additional grouping metadata.

customerGroup string

Possible values: <= 64 characters

productGroup string

Possible values: <= 64 characters

payment

object

required

Transactional metadata for the registration payment.

amount decimalrequired

Possible values: >= 0.01

Amount for the registration payment (minimum 0.01).

currencyCode stringrequired

Possible values: Value must match regular expression ^[A-Z]{3}$

ISO 4217 currency code.

description stringrequired

Possible values: <= 127 characters

Short description of the transaction.

shopCountry string

Possible values: Value must match regular expression ^[A-Z]{2}$

ISO 3166-1 alpha-2 country code of the shop.

Responses

201

Payment option successfully stored

application/json

Schema

Schema

storedPaymentOptionReference string

Possible values: <= 64 characters

Unique identifier of the stored payment option.

cardDetails

object

Metadata about the stored card.

cardBrand string

Possible values: <= 16 characters

Brand of the card.

cardHolder string

Possible values: <= 64 characters

Name of the cardholder.

cardToken string

Possible values: <= 64 characters

Tokenized card identifier used for MIT.

cvvToken string

Possible values: <= 32 characters

Optional CVV token if stored securely.

cardExpiryMonth string

Possible values: Value must match regular expression ^(0[1-9]|1[0-2])$

Expiration month of the stored card.

cardExpiryYear string

Possible values: Value must match regular expression ^20\d{2}$

Expiration year of the stored card.

Example (from schema)

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

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

Loading...