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.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Value: "payment-card"

The method of payment instrument.

customerId
string <= 50 characters

The сustomer's ID.

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

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

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
Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"

Payment Card brand.

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 <date-time> Nullable

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.

Request samples

$paymentInstruments = $client->paymentInstruments()->search([
    'filter' => 'status:active;method:payment-card',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create a Payment Instrument

Create a payment instrument. If such payment card or bank account payment instrument already exists then updates it instead.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

The payment instrument ID.

method
string
Value: "payment-card"

The method of payment instrument.

customerId
string <= 50 characters

The сustomer's ID.

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

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

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
Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"

Payment Card brand.

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 <date-time> Nullable

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.

Request samples

Content type
application/json
Example
{
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "token": "string",
  • "customFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

The payment instrument ID.

method
string
Value: "payment-card"

The method of payment instrument.

customerId
string <= 50 characters

The сustomer's ID.

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

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

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
Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"

Payment Card brand.

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 <date-time> Nullable

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.

Request samples

$paymentInstrument = $client->paymentInstruments()->load('paymentInstrumentId');

Response samples

Content type
application/json
Example
{
  • "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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

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

The payment instrument ID.

method
string
Value: "payment-card"

The method of payment instrument.

customerId
string <= 50 characters

The сustomer's ID.

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

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

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
Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"

Payment Card brand.

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 <date-time> Nullable

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.

Request samples

Content type
application/json
Example
{
  • "token": "string",
  • "billingAddress": {
    },
  • "customFields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

The payment instrument ID.

method
string
Value: "payment-card"

The method of payment instrument.

customerId
string <= 50 characters

The сustomer's ID.

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

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

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
Enum: "Visa" "MasterCard" "American Express" "Discover" "Maestro" "Solo" "Electron" "JCB" "Voyager" "Diners Club" "Switch" "Laser" "China UnionPay" "AstroPay Card"

Payment Card brand.

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 <date-time> Nullable

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.

Request samples

$client->paymentInstruments()->deactivate('paymentInstrumentId');

Response samples

Content type
application/json
Example
{
  • "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": [
    ]
}