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
- Start with order
GETthe link with rel: paymentinstrumentselectorGETthe link with rel: choicePOSTthe 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
- 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 |
|---|---|---|
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
- 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 |
|---|---|---|
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
- 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 |
|---|---|---|
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 |