Paymentinstruments

Payment instruments are specific, concrete instances of a payment method, such as a credit card, individual cheque, or other form of payment. Payment providers require specific creation information, provided through third-party-defined payment instructions to instantiate valid payment instruments.

Read Payment Instruments from Profile

Reads a list of the shopper’s payment instruments.

Workflow

1. Start with profile
2. GET the link with rel: paymentinstruments
3. Render the response

Read Payment Instruments from Account

Reads a list of the account’s payment instruments.

Workflow

1. Start with account
2. GET the link with rel: paymentinstruments
3. Render the response

Read Payment Instrument

Reads a payment instrument from a list of payment instruments.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: element
3. Render the response

Response

Type: paymentinstruments.payment-instrument

Name	Description	Type
payment-instrument-identification-attributes	Payment instrument-specific attributes, underscoring the individual payment instrument and differentiating it from other instruments. These attributes might include a payment token or time to live.	object
default-on-profile	Indicates whether a payment instrument is the default one for a profile.	boolean
name	The payment instrument name.	string

Sample

{
  "self": {
    "type": "paymentinstruments.payment-instrument",
    "uri": "/paymentinstruments/mobee/mfston3dhfstqljtmnrteljugy4tcllcmqzgellbgq4wkyjrmi3wemrrgm=",
    "href": "https://cortex.elasticpath.com/cortex/paymentinstruments/mobee/mfston3dhfstqljtmnrteljugy4tcllcmqzgellbgq4wkyjrmi3wemrrgm="
  },
  "messages": [],
  "links": [
    {
      "rel": "paymentmethod",
      "type": "paymentmethods.profile-payment-method",
      "href": "https://cortex.elasticpath.com/cortex/paymentmethods/profiles/mobee/ovzwk4tumvzxiz3vnfsa=/geyggobtgiztaljrgvrdqljugy4dcllcg42tmljugjrggyrxhbqtonrxgy="
    },
    {
      "rel": "paymentinstruments",
      "type": "paymentinstruments.payment-instruments",
      "href": "https://cortex.elasticpath.com/cortex/paymentinstruments/mobee"
    }
  ],
  "default-on-profile": true,
  "name": "test",
  "payment-instrument-identification-attributes": {}
}

Delete Payment Instrument

Delete the payment instrument from the profile or account.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: element
3. DELETE payment instrument

Add Payment Instrument

Use to add a payment instrument to the profile or account.

Workflow

1. Start with payment method
2. GET the link with rel: paymentinstrumentform
3. Fill out the form
4. POST the form using the link with rel: createpaymentinstrumentaction

Request Fields

Type: paymentinstruments.payment-instrument-for-form

Name	Description	Type
default-on-profile	Indicates whether to set a payment instrument as the default one on a profile.	boolean
name	The shopper identifiable name of a payment instrument, such as "My Amex" or "My Visa".	string
payment-instrument-identification-form	Payment instrument-specific attributes, underscoring the individual payment instrument through dynamic fields required by the payment gateway for payment instrument creation. Populate these fields with payment instrument identification information returned by the third-party payment gateway, such as a payment token.	object
billing-address	Billing address information to attach to the payment instrument.	object
name	The customer name.	object
given-name	The person’s given name.	string
family-name	The person’s family name.	string
address	The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.	object
street-address	The street address.	string
extended-address	An extra field for address information. This field is optional.	string
locality	The city name.	string
region	The region name. A region typically corresponds to a province or a state of a country.	string
postal-code	The postal code or zip code.	string
country-name	The country name.	string
phone-number	The phone number.	string
organization	The organization.	string

Read Default Payment Instrument

Reads the default payment instrument.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: default
3. Render the response

Response Fields

Type: paymentinstruments.payment-instrument

Name	Description	Type
payment-instrument-identification-attributes	Payment instrument-specific attributes, underscoring the individual payment instrument and differentiating it from other instruments. These attributes might include a payment token or time to live.	object
default-on-profile	Indicates whether a payment instrument is the default one for a profile.	boolean
name	The payment instrument name.	string

Read Chosen Default Payment Instrument

Use the profile’s default payment instrument selector to read the chosen instrument.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: defaultinstrumentselector
3. GET the link with rel: chosen
4. GET the link with rel: description
5. Render the response

Response Fields

Type: paymentinstruments.payment-instrument

Name	Description	Type
payment-instrument-identification-attributes	Payment instrument-specific attributes, underscoring the individual payment instrument and differentiating it from other instruments. These attributes might include a payment token or time to live.	object
default-on-profile	Indicates whether a payment instrument is the default one for a profile.	boolean
name	The payment instrument name.	string

Read Default Payment Instrument Choice

Use the profile’s default payment instrument selector to read a choice.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: defaultinstrumentselector
3. GET the link with rel: choice
4. GET the link with rel: description
5. Render the response

Response Fields

Type: paymentinstruments.payment-instrument

Name	Description	Type
payment-instrument-identification-attributes	Payment instrument-specific attributes, underscoring the individual payment instrument and differentiating it from other instruments. These attributes might include a payment token or time to live.	object
default-on-profile	Indicates whether a payment instrument is the default one for a profile.	boolean
name	The payment instrument name.	string

Select Default Payment Instrument

Use the profile’s default payment instrument selector to select a payment instrument.

Workflow

1. Start with profile payment instruments or account payment instruments
2. GET the link with rel: defaultinstrumentselector
3. GET the link with rel: choice
4. POST the choice using the link with rel: selectaction