Create a payment instrument
Creates and activates a new payment instrument resource by saving a payment card for an identified customer. Implement to improve customer experience by skipping the step of entering payment instrument details.
The token created via this endpoint can not be used for recurring payments by merchants operating within the EU. For more information visit our recurring payments guide.
- application/json
Request Body
- type string required
Possible values: [
card
]Type of the payment instrument.
card object required
Required when payment type is
card
. Details of the payment card.name string requiredName of the cardholder as it appears on the payment card.
number string requiredNumber of the payment card (without spaces).
expiry_year string requiredPossible values:
>= 2 characters
and<= 4 characters
Year from the expiration time of the payment card. Accepted formats are
YY
andYYYY
.expiry_month string requiredPossible values: [
01
,02
,03
,04
,05
,06
,07
,08
,09
,10
,11
,12
]Month from the expiration time of the payment card. Accepted format is
MM
.cvv string requiredPossible values:
>= 3 characters
and<= 4 characters
Three or four-digit card verification value (security code) of the payment card.
zip_code stringPossible values:
>= 5 characters
and<= 5 characters
Required five-digit ZIP code. Applicable only to merchant users in the USA.
- 201
- 400
- 401
- 403
- 404
- 409
Created
- application/json
- Schema
- Example (from schema)
Schema
- token string
Unique token identifying the saved payment card for a customer.
- active boolean
Default value:
true
Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a
DELETE
request to the resource endpoint. - type string
Possible values: [
card
]Type of the payment instrument.
card object
Details of the payment card.
last_4_digits stringPossible values:
>= 4 characters
and<= 4 characters
Last 4 digits of the payment card number.
type stringPossible values: [
AMEX
,CUP
,DINERS
,DISCOVER
,ELO
,ELV
,HIPERCARD
,JCB
,MAESTRO
,MASTERCARD
,VISA
,VISA_ELECTRON
,VISA_VPAY
,UNKNOWN
]Issuing card network of the payment card.
mandate object
Created mandate
type stringIndicates the mandate type
status stringMandate status
merchant_code stringMerchant code which has the mandate
- created_at date-time
Creation date of payment instrument. Response format expressed according to ISO8601 code.
{
"token": "string",
"active": true,
"type": "card",
"card": {
"last_4_digits": "string",
"type": "AMEX"
},
"mandate": {
"type": "string",
"status": "string",
"merchant_code": "string"
},
"created_at": "2023-06-02"
}
Bad Request
- application/json
- Schema
- Example (from schema)
- Invalid_ Parameter
- Multiple_ Invalid_ Parameters
Schema
- MOD1
- MOD2
- message string
Short description of the error.
- error_code string
Platform code for the error.
- param string
Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example,
card.name
refers to thename
parameter embedded in thecard
object. - allOf
{
"message": "string",
"error_code": "string",
"param": "string"
}
{
"message": "Validation error",
"error_code": "INVALID",
"param": "card.expiry_year"
}
[
{
"error_code": "INVALID",
"message": "Validation error",
"param": "card.name"
},
{
"error_code": "INVALID",
"message": "Validation error",
"param": "card.number"
},
{
"error_code": "INVALID",
"message": "Validation error",
"param": "card.expiry_year"
}
]
Unauthorized
- application/json
- Schema
- Example (from schema)
- Invalid_ Token
- Not_ Authorized_ Token
- Missing_ Token
Schema
- message string
Short description of the error.
- error_code string
Platform code for the error.
{
"message": "string",
"error_code": "string"
}
{
"error_message": "invalid access token",
"error_code": "NOT_AUTHORIZED"
}
{
"error_message": "NOT_AUTHORIZED",
"error_code": "NOT_AUTHORIZED"
}
{
"message": "access token required",
"error_code": "NOT_AUTHORIZED"
}
Forbidden
- application/json
- Schema
- Example (from schema)
- Forbidden
Schema
- error_message string
Short description of the error.
- error_code string
Platform code for the error.
- status_code string
HTTP status code for the error.
{
"error_message": "string",
"error_code": "string",
"status_code": "string"
}
{
"error_message": "request_not_allowed",
"error_code": "FORBIDDEN",
"status_code": 403
}
Not Found
- application/json
- Schema
- Example (from schema)
- Not_ Found
Schema
- message string
Short description of the error.
- error_code string
Platform code for the error.
{
"message": "string",
"error_code": "string"
}
{
"error_code": "NOT_FOUND",
"message": "Resource not found"
}
Conflict
- application/json
- Schema
- Example (from schema)
- Checkout_ Processed
Schema
- message string
Short description of the error.
- error_code string
Platform code for the error.
{
"message": "string",
"error_code": "string"
}
{
"error_code": "MAX_INSTRUMENT_COUNT",
"message": "Max number of payment instruments on file reached"
}