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

• card object required

  Required when payment type is card. Details of the payment card.

  cvv string required

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

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

  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.

  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.

  name string required

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

  number string required

  Number of the payment card (without spaces).

  zip_code string

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

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

• type string required

  Possible values: [card]

  Type of the payment instrument.

Responses

• 201
• 400
• 401
• 403
• 404
• 409

---

Created

application/json

• Schema
• Example (from schema)

---

Schema

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

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

• created_at date-time

  Creation date of payment instrument. Response format expressed according to ISO8601 code.

• mandate object

  Created mandate

  merchant_code string

  Merchant code which has the mandate

  status string

  Mandate status

  type string

  Indicates the mandate type

• token string

  Unique token identifying the saved payment card for a customer.

• type string

  Possible values: [card]

  Type of the payment instrument.

{
  "active": true,
  "card": {
    "last_4_digits": "string",
    "type": "AMEX"
  },
  "created_at": "2023-09-21",
  "mandate": {
    "merchant_code": "string",
    "status": "string",
    "type": "string"
  },
  "token": "string",
  "type": "card"
}

Bad Request

application/json

• Schema
• Example (from schema)
• Invalid_ Parameter
• Multiple_ Invalid_ Parameters

---

Schema

oneOf
• MOD1
• MOD2
---
error_code string
Platform code for the error.
message string
Short description of 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

{
  "error_code": "string",
  "message": "string",
  "param": "string"
}

{
  "error_code": "INVALID",
  "message": "Validation error",
  "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
• Missing_ Token
• Not_ Authorized_ Token

---

Schema

• error_code string

  Platform code for the error.

• message string

  Short description of the error.

{
  "error_code": "string",
  "message": "string"
}

{
  "error_code": "NOT_AUTHORIZED",
  "error_message": "invalid access token"
}

{
  "error_code": "NOT_AUTHORIZED",
  "message": "access token required"
}

{
  "error_code": "NOT_AUTHORIZED",
  "error_message": "NOT_AUTHORIZED"
}

Forbidden

application/json

• Schema
• Example (from schema)
• Forbidden

---

Schema

• error_code string

  Platform code for the error.

• error_message string

  Short description of the error.

• status_code string

  HTTP status code for the error.

{
  "error_code": "string",
  "error_message": "string",
  "status_code": "string"
}

{
  "error_code": "FORBIDDEN",
  "error_message": "request_not_allowed",
  "status_code": "403"
}

Not Found

application/json

• Schema
• Example (from schema)
• Not_ Found

---

Schema

• error_code string

  Platform code for the error.

• message string

  Short description of the error.

{
  "error_code": "string",
  "message": "string"
}

{
  "error_code": "NOT_FOUND",
  "message": "Resource not found"
}

Conflict

application/json

• Schema
• Example (from schema)
• Checkout_ Processed

---

Schema

• error_code string

  Platform code for the error.

• message string

  Short description of the error.

{
  "error_code": "string",
  "message": "string"
}

{
  "error_code": "MAX_INSTRUMENT_COUNT",
  "message": "Max number of payment instruments on file reached"
}