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.

Select Order Payment Instrument

The payment instrument selector resource provides the shopper with a selector to choose the payment instrument to use for the purchase. If the shopper is transacting on behalf of an account, for example if the x-ep-account-shared-id header is set, the selector returns the payment instruments stored on the account. If not, the selector returns the payment instruments stored on the shopper profile.

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 an available payment instrument choice.

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

Add Order Payment Instrument

Submit a payment instrument form from 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	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