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 Cart 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
- Start with order
GETthe link with rel: paymentinstrumentselectorGETthe link with rel: choicePOSTthe choice using the link with rel: selectaction
Read Cart Order Payment Instrument Choice
Use the cart order payment instrument selector to read an available payment instrument choice.
Workflow
- Start with order
GETthe link with rel: paymentinstrumentselectorGETthe link with rel: choiceGETthe link with rel: description- Render the response
Response Fields
Type: paymentinstruments.payment-instrument
| Name | Description | Type |
|---|---|---|
name | Payment instrument name. | string |
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 |
Read Chosen Cart Order Payment Instrument
Use the cart order payment instrument selector to read the chosen payment instruments.
Workflow
- Start with order
GETthe link with rel: paymentinstrumentselectorGETthe link with rel: chosenGETthe link with rel: description- Render the response
Response Fields
Type: paymentinstruments.order-payment-instrument
| Name | Description | Type |
|---|---|---|
name | The payment instrument name. | string |
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 |
saved-on-profile | Indicates whether a payment instrument is saved on a profile. | boolean |
default-on-profile | Indicates whether a payment instrument is the default one for a profile. | boolean |
limit-amount | Describes the max amount allowed to be charged to the payment instrument. | object |
currency | The currency the payment is in. | string |
amount | The decimal value of the payment limit amount. | decimal |
display | Formatted currency string that can be displayed on the client application. | string |
Update Chosen Cart Order Payment Instrument
Use the cart order payment instrument selector to update the limit on the chosen payment instruments.
Workflow
- Start with order
GETthe link with rel: paymentinstrumentselectorGETthe link with rel: chosenGETthe link with rel: description- Update payment instrument using a
PUTrequest
Add Cart Order Payment Instrument
Create a new payment instrument on the cart order.
Workflow
- Start with order payment method
GETthe link with rel: paymentinstrumentform- Fill out the form
POSTthe form using the link with rel: createpaymentinstrumentaction
Request Fields
Type: paymentinstruments.order-payment-instrument-for-form
| Name | Description | Type |
|---|---|---|
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 |
limit-amount | Specifies the limit on the payment instrument. Note that 0 means unlimited. Exactly one payment instrument must be unlimited to allow checkout. | 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 |
billing-address | Billing address information to attach to the payment instrument. Note that this may not appear for all payment methods. | 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 | Street address line 1. | string |
street-address-2 | Street address line 2. This field is optional. | string |
street-address-3 | Street address line 3. 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 |