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 required

  Name of the cardholder as it appears on the payment card.

  number string required

  Number of the payment card (without spaces).

  expiry_year string required

  Possible values: >= 2 characters and <= 4 characters

  Year from the expiration time of the payment card. Accepted formats are YY and YYYY.

  expiry_month string required

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

  Possible values: >= 3 characters and <= 4 characters

  Three or four-digit card verification value (security code) of the payment card.

  zip_code string

  Possible values: >= 5 characters and <= 5 characters

  Required five-digit ZIP code. Applicable only to merchant users in the USA.

Responses

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

  Possible values: >= 4 characters and <= 4 characters

  Last 4 digits of the payment card number.

  type string

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

  Indicates the mandate type

  status string

  Mandate status

  merchant_code string

  Merchant 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

oneOf
• 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 the name parameter embedded in the card 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"
}