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, in order to instantiate valid payment instruments.

Read Payment Instruments

Read the list of payment instruments created on the profile.

Workflow

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

Read Payment Instrument

Read the payment instrument previously created on the profile.

Workflow

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

Response Fields

Type: paymentinstruments.payment-instrument

Name	Description	Type
payment-instrument-identification-attributes	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	Payment instrument name.	string

Add Payment Instrument

Submit a payment instrument form from the profile.

Workflow

1. Start with profile-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	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	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	Postal code or zip code.	string
country-name	The country name.	string
phone-number	Phone number	string
organization	The organization	string

Select Order Payment Instrument

Select a payment instrument to be used on the order.

Workflow

1. Start with order
2. GET the link with rel: paymentinstrumentselector
3. GET the link with rel: choice
4. POST the choice using the link with rel: selectaction

Read Payment Instrument Choice

Use the order payment instrument selector to read a payment instrument choice available from profile.

Workflow

1. Start with order
2. GET the link with rel: paymentinstrumentselector
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	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	Payment instrument name.	string

Read Chosen Order Payment Instrument

Use the order payment instrument selector to read the chosen order payment instrument.

Workflow

1. Start with order
2. GET the link with rel: paymentinstrumentselector
3. GET the link with rel: chosen
4. GET the link with rel: description
5. Render the response

Response Fields

Type: paymentinstruments.order-payment-instrument

Name	Description	Type
limit-amount	Describes the limit on the payment instrument.	object
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
saved-on-profile	Indicates whether a payment instrument is saved on a profile.	boolean
payment-instrument-identification-attributes	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	Payment instrument name.	string

Add Order Payment Instrument

Submit a payment instrument form from the order.

Workflow

1. Start with order-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.order-payment-instrument-for-form

Name	Description	Type
limit-amount	Describes the limit on the payment instrument.	decimal
save-on-profile	Indicates whether to save a payment instrument on a profile.	boolean
default-on-profile	Indicates whether to set a payment instrument as the default one on a profile.	boolean
name	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	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	Postal code or zip code.	string
country-name	The country name.	string
phone-number	Phone number	string
organization	The organization	string

Read Default Payment Instrument

Read the profile’s default payment instrument.

Workflow

1. Start with 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	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	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 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	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	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 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	Indicates specific attributes for the individual payment instrument, such as payment token. These attributes differentiate it from other payment instruments.	object
default-on-profile	Indicates if this is the default payment instrument on the profile.	boolean
name	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 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