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
- Start with profile
GETthe link with rel: paymentinstruments- Render the response
Read Payment Instrument
Read the payment instrument previously created on the profile.
Workflow
- Start with payment-instruments
GETthe link with rel: element- 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
- Start with profile-payment-method
GETthe link with rel: paymentinstrumentform- Fill out the form
POSTthe 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
- 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 a payment instrument choice available from profile.
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 | 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
- 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 | 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
- 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 | 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
- Start with payment-instruments
GETthe link with rel: default- 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
- Start with payment-instruments
GETthe link with rel: defaultinstrumentselectorGETthe link with rel: chosenGETthe link with rel: description- 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
- Start with payment-instruments
GETthe link with rel: defaultinstrumentselectorGETthe link with rel: choiceGETthe link with rel: description- 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
- Start with payment-instruments
GETthe link with rel: defaultinstrumentselectorGETthe link with rel: choicePOSTthe choice using the link with rel: selectaction