Payment Instruments

The Payment Instrument allows you to accept a variety of payment methods through a single API.

Retrieve a list of payment instruments

Retrieve a list of payment instruments.

Request
Security:
query Parameters
filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of payment instruments was retrieved successfully.
Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
One of:
id
string <= 50 characters

The payment instrument ID.

method
string

The method of payment instrument.

Value: "payment-card"
customerId
string <= 50 characters

The сustomer's ID.

status
string

Payment instrument status. When an instrument is active it means it has been used at least once for an approved transaction. To remove an instrument from being in use, set it as deactivated (see the deactivation endpoint).

Enum: "active" "inactive" "expired" "deactivated" "verification-needed"
fingerprint
string

A unique value to identify the payment instrument regardless of variable values. It contains alphanumeric values.

bin
string <bin>

The card's bin (the PAN's first 6 digits).

last4
string

The PAN's last 4 digits.

expYear
integer

Card's expiration year.

expMonth
integer

Card's expiration month.

brand
string

Payment Card brand.

Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

createdTime
string <date-time>

Payment instrument created time.

updatedTime
string <date-time>

Payment instrument updated time.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

stickyGatewayAccountId
string

Default gateway account ID used for transactions.

expirationReminderTime
string or null <date-time>

Time expiration reminder event will be triggered.

expirationReminderNumber
integer

Number of expiration reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or AuthTransactionLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of AuthTransactionEmbed (object) or CustomerEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/payment-instruments
Request samples
$paymentInstruments = $client->paymentInstruments()->search([
    'filter' => 'status:active;method:payment-card',
]);
Response samples
application/json
[
  • {
    }
]

Create a Payment Instrument

Create a payment instrument. If such payment card, bank account or alternative payment instrument already exists then it is updated instead.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

PaymentInstrument resource.

Any of:
customerId
required
string <= 50 characters

The customer's ID.

token
required
string

Payment token ID.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

Responses
201Payment instrument was created.
Response Schema: application/json
One of:
id
string <= 50 characters

The payment instrument ID.

method
string

The method of payment instrument.

Value: "payment-card"
customerId
string <= 50 characters

The сustomer's ID.

status
string

Payment instrument status. When an instrument is active it means it has been used at least once for an approved transaction. To remove an instrument from being in use, set it as deactivated (see the deactivation endpoint).

Enum: "active" "inactive" "expired" "deactivated" "verification-needed"
fingerprint
string

A unique value to identify the payment instrument regardless of variable values. It contains alphanumeric values.

bin
string <bin>

The card's bin (the PAN's first 6 digits).

last4
string

The PAN's last 4 digits.

expYear
integer

Card's expiration year.

expMonth
integer

Card's expiration month.

brand
string

Payment Card brand.

Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

createdTime
string <date-time>

Payment instrument created time.

updatedTime
string <date-time>

Payment instrument updated time.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

stickyGatewayAccountId
string

Default gateway account ID used for transactions.

expirationReminderTime
string or null <date-time>

Time expiration reminder event will be triggered.

expirationReminderNumber
integer

Number of expiration reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or AuthTransactionLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of AuthTransactionEmbed (object) or CustomerEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

303Payment instrument was updated.
401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/payment-instruments
Request samples
application/json
{
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "token": "string",
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "riskMetadata": {
    },
  • "stickyGatewayAccountId": "string",
  • "expirationReminderTime": "2019-08-24T14:15:22Z",
  • "expirationReminderNumber": 0,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve a Payment Instrument

Retrieve a payment instrument by ID.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Payment Instrument was retrieved successfully.
Response Schema: application/json
One of:
id
string <= 50 characters

The payment instrument ID.

method
string

The method of payment instrument.

Value: "payment-card"
customerId
string <= 50 characters

The сustomer's ID.

status
string

Payment instrument status. When an instrument is active it means it has been used at least once for an approved transaction. To remove an instrument from being in use, set it as deactivated (see the deactivation endpoint).

Enum: "active" "inactive" "expired" "deactivated" "verification-needed"
fingerprint
string

A unique value to identify the payment instrument regardless of variable values. It contains alphanumeric values.

bin
string <bin>

The card's bin (the PAN's first 6 digits).

last4
string

The PAN's last 4 digits.

expYear
integer

Card's expiration year.

expMonth
integer

Card's expiration month.

brand
string

Payment Card brand.

Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

createdTime
string <date-time>

Payment instrument created time.

updatedTime
string <date-time>

Payment instrument updated time.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

stickyGatewayAccountId
string

Default gateway account ID used for transactions.

expirationReminderTime
string or null <date-time>

Time expiration reminder event will be triggered.

expirationReminderNumber
integer

Number of expiration reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or AuthTransactionLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of AuthTransactionEmbed (object) or CustomerEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/payment-instruments/{id}
Request samples
$paymentInstrument = $client->paymentInstruments()->load('paymentInstrumentId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "riskMetadata": {
    },
  • "stickyGatewayAccountId": "string",
  • "expirationReminderTime": "2019-08-24T14:15:22Z",
  • "expirationReminderNumber": 0,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Update a Payment Instrument's values

Update allowed payment instrument's values.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

PaymentInstrument resource.

One of:
token
string

Payment token ID.

object

The billing address (if supplied – overrides billing address from token).

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

Responses
200Payment instrument was updated.
Response Schema: application/json
One of:
id
string <= 50 characters

The payment instrument ID.

method
string

The method of payment instrument.

Value: "payment-card"
customerId
string <= 50 characters

The сustomer's ID.

status
string

Payment instrument status. When an instrument is active it means it has been used at least once for an approved transaction. To remove an instrument from being in use, set it as deactivated (see the deactivation endpoint).

Enum: "active" "inactive" "expired" "deactivated" "verification-needed"
fingerprint
string

A unique value to identify the payment instrument regardless of variable values. It contains alphanumeric values.

bin
string <bin>

The card's bin (the PAN's first 6 digits).

last4
string

The PAN's last 4 digits.

expYear
integer

Card's expiration year.

expMonth
integer

Card's expiration month.

brand
string

Payment Card brand.

Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

createdTime
string <date-time>

Payment instrument created time.

updatedTime
string <date-time>

Payment instrument updated time.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

stickyGatewayAccountId
string

Default gateway account ID used for transactions.

expirationReminderTime
string or null <date-time>

Time expiration reminder event will be triggered.

expirationReminderNumber
integer

Number of expiration reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or AuthTransactionLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of AuthTransactionEmbed (object) or CustomerEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
422Invalid data was sent.
patch/payment-instruments/{id}
Request samples
application/json
{
  • "token": "string",
  • "billingAddress": {
    },
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "riskMetadata": {
    },
  • "stickyGatewayAccountId": "string",
  • "expirationReminderTime": "2019-08-24T14:15:22Z",
  • "expirationReminderNumber": 0,
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Deactivate a payment instrument

Deactivate a payment instrument.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
201Payment instrument was deactivated.
Response Schema: application/json
One of:
id
string <= 50 characters

The payment instrument ID.

method
string

The method of payment instrument.

Value: "payment-card"
customerId
string <= 50 characters

The сustomer's ID.

status
string

Payment instrument status. When an instrument is active it means it has been used at least once for an approved transaction. To remove an instrument from being in use, set it as deactivated (see the deactivation endpoint).

Enum: "active" "inactive" "expired" "deactivated" "verification-needed"
fingerprint
string

A unique value to identify the payment instrument regardless of variable values. It contains alphanumeric values.

bin
string <bin>

The card's bin (the PAN's first 6 digits).

last4
string

The PAN's last 4 digits.

expYear
integer

Card's expiration year.

expMonth
integer

Card's expiration month.

brand
string

Payment Card brand.

Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

createdTime
string <date-time>

Payment instrument created time.

updatedTime
string <date-time>

Payment instrument updated time.

customFields
object (ResourceCustomFields)
Default: {}

Custom Fields list as a map {"custom field name": "custom field value", ...}. The format must follow the saved format (see Custom Fields section for the formats).

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

stickyGatewayAccountId
string

Default gateway account ID used for transactions.

expirationReminderTime
string or null <date-time>

Time expiration reminder event will be triggered.

expirationReminderNumber
integer

Number of expiration reminder events triggered.

Array of SelfLink (object) or CustomerLink (object) or AuthTransactionLink (object) or ApprovalUrlLink (object) non-empty

The links related to resource.

Array of AuthTransactionEmbed (object) or CustomerEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
409Conflict.
post/payment-instruments/{id}/deactivation
Request samples
$client->paymentInstruments()->deactivate('paymentInstrumentId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "riskMetadata": {
    },
  • "stickyGatewayAccountId": "string",
  • "expirationReminderTime": "2019-08-24T14:15:22Z",
  • "expirationReminderNumber": 0,
  • "_links": [
    ],
  • "_embedded": [
    ]
}