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.

SecurityCustomerJWT
Request
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.

Responses
200

A list of payment instrument 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 resource ID. Defaults to UUID v4.

method
string

The method of payment instrument.

Value: "payment-card"
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" … 4 more
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array of objects (ContactEmails)

The list of emails.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

useAsBackup
boolean
Default: false

Allow using this payment instrument as a backup for invoice payment retries.

billingPortalUrl
string

URL to the billing portal where the card can be updated.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

token
string or null

New customer JWT for further requests. Will be null if customer is already authenticated.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/payment-instruments
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/payment-instruments?filter=string&sort=string&limit=1000&offset=0&q=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
[
  • {
    }
]

Create a Payment Instrument

Create a payment instrument.

The only way to create a payment instrument is using a payment instrument token pre-created via FramePay.

SecurityCustomerJWT or PublishableApiKey
Request
Request Body schema: application/json

Payment instrument.

token
required
string

Payment instrument 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
201

Payment instrument was created.

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

The resource ID. Defaults to UUID v4.

method
string

The method of payment instrument.

Value: "payment-card"
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" … 4 more
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

useAsBackup
boolean
Default: false

Allow using this payment instrument as a backup for invoice payment retries.

billingPortalUrl
string

URL to the billing portal where the card can be updated.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

token
string or null

New customer JWT for further requests. Will be null if customer is already authenticated.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/payment-instruments
Request samples
application/json
{
  • "token": "string",
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "useAsBackup": false,
  • "billingPortalUrl": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "token": "string",
  • "_links": [
    ]
}

Retrieve a Payment Instrument

Retrieve a payment instrument by ID.

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

The resource identifier string.

query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

Responses
200

Payment Instrument 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
One of:
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

method
string

The method of payment instrument.

Value: "payment-card"
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" … 4 more
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

useAsBackup
boolean
Default: false

Allow using this payment instrument as a backup for invoice payment retries.

billingPortalUrl
string

URL to the billing portal where the card can be updated.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

token
string or null

New customer JWT for further requests. Will be null if customer is already authenticated.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/payment-instruments/{id}
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/payment-instruments/{id}?limit=1000&offset=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "useAsBackup": false,
  • "billingPortalUrl": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "token": "string",
  • "_links": [
    ]
}

Update a Payment Instrument's values

Update any of the payment instrument's values.

Use Framepay payment token to update desired values.

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

The resource identifier string.

Request Body schema: application/json

Payment instrument.

token
string

Payment instrument token ID.

object

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

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

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
200

Payment instrument was updated.

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

The resource ID. Defaults to UUID v4.

method
string

The method of payment instrument.

Value: "payment-card"
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" … 4 more
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

useAsBackup
boolean
Default: false

Allow using this payment instrument as a backup for invoice payment retries.

billingPortalUrl
string

URL to the billing portal where the card can be updated.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

token
string or null

New customer JWT for further requests. Will be null if customer is already authenticated.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid 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",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "useAsBackup": false,
  • "billingPortalUrl": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "token": "string",
  • "_links": [
    ]
}

Deactivate a Payment Instrument

Deactivate a payment instrument.

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

The resource identifier string.

Responses
201

Deactivation successful.

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

The resource ID. Defaults to UUID v4.

method
string

The method of payment instrument.

Value: "payment-card"
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" … 4 more
bankCountry
string

Payment instrument bank country.

bankName
string

Payment instrument bank name.

object

The billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

useAsBackup
boolean
Default: false

Allow using this payment instrument as a backup for invoice payment retries.

billingPortalUrl
string

URL to the billing portal where the card can be updated.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

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

token
string or null

New customer JWT for further requests. Will be null if customer is already authenticated.

Array of SelfLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

post/payment-instruments/{id}/deactivation
Request samples
const paymentInstrument = await api.paymentInstruments.deactivate({id: 'id-to-deactivate'});

console.log(paymentInstrument.fields.status);
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "method": "payment-card",
  • "status": "active",
  • "fingerprint": "string",
  • "bin": "string",
  • "last4": "string",
  • "expYear": 0,
  • "expMonth": 0,
  • "brand": "Visa",
  • "bankCountry": "string",
  • "bankName": "string",
  • "billingAddress": {
    },
  • "useAsBackup": false,
  • "billingPortalUrl": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "customFields": {
    },
  • "token": "string",
  • "_links": [
    ]
}

Retrieve the payment instrument's setup transaction

Retrieve the latest setup transaction for the given payment instrument.

More information about all the related setup transactions is available at the Transaction endpoints.

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

The resource identifier string.

Responses
200

Setup transaction was retrieved successfully.

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

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string = 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string = 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string = 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object (InstrumentReference)
method
required
string (PaymentMethod)

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 155 more
paymentInstrumentId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object

Billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

has3ds
boolean
object
server
string

3D Secure server name.

version
string

3D Secure version.

Enum: "1.0.2" "2.1.0" "2.2.0"
enrolled
string

Is the cardholder enrolled in 3D Secure.

Enum: "yes" "no" "invalid card/timeout" "unavailable"
authenticated
string

3D Secure authentication response status.

Enum: "yes" "no" "not applicable" "attempted"
liability
string
Enum: "protected" "not protected" "protected (attempt)"
flow
string

3D Secure 2 authentication flow.

Enum: "frictionless" "challenge"
isDowngraded
boolean
Default: false

If 3D Secure 2 was attempted but downgraded to 3D Secure 1.

redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 164 more
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).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

approvalUrl
string <uri>

The URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

The session's token used for authentication. It would allow to visit created order, invoice and transaction.

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

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/payment-instruments/{id}/setup
Request samples
curl -i -X GET \
  'https://api-sandbox.rebilly.com/storefront/payment-instruments/{id}/setup' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "type": "3ds-authentication",
  • "status": "completed",
  • "result": "abandoned",
  • "amount": 0,
  • "currency": "USD",
  • "purchaseAmount": 0,
  • "purchaseCurrency": "USD",
  • "requestAmount": 0,
  • "requestCurrency": "USD",
  • "parentTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "childTransactions": [
    ],
  • "invoiceIds": [
    ],
  • "subscriptionIds": [
    ],
  • "planIds": [
    ],
  • "isRebill": true,
  • "rebillNumber": 0,
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "has3ds": true,
  • "3ds": {
    },
  • "redirectUrl": "http://example.com",
  • "retryNumber": 0,
  • "isRetry": true,
  • "billingDescriptor": "string",
  • "description": "string",
  • "requestId": "string",
  • "hasAmountAdjustment": true,
  • "gatewayName": "A1Gateway",
  • "customFields": {
    },
  • "processedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "approvalUrl": "http://example.com",
  • "token": "string",
  • "_links": [
    ]
}

Create the payment instrument's setup transaction

Create the payment instrument's setup transaction.

This effectively makes the payment instrument available for further payments. The response should be treated as a regular transaction; for example, the approval links should be followed until the transaction is completed.

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

The resource identifier string.

Request Body schema: application/json

Setup Transaction resource.

websiteId
required
string <= 50 characters

The resource ID. Defaults to UUID v4.

currency
required
string (CurrencyCode) = 3 characters

ISO 4217 alphabetic currency code.

amount
number <double>
Default: 0

The transaction amount.

object or null

Billing address. If not supplied, it takes the billing address associated with the payment instrument, and then customer's address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

redirectUrl
string or null <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL. You may use {id} or {result} as placeholders in the URL and it will be replaced with the transaction's id and result accordingly.

object (Risk metadata)

Risk metadata used for 3DS and risk scoring.

ipAddress
string <ipv4 or ipv6>

The customer's IP.

fingerprint
string <= 50 characters

The fingerprint.

object (HttpHeaders)

The HTTP headers.

property name*
additional property
string
object (Browser data)

Browser data used for 3DS and risk scoring.

colorDepth
required
integer [ 1 .. 48 ]

The browser's color depth in bits per pixel obtained using the screen.colorDepth property.

isJavaEnabled
required
boolean

Whether Java is enabled in a browser or not. Value is returned from the navigator.javaEnabled property.

language
required
string <= 8 characters

The browser's language settings returned from the navigator.language property.

screenWidth
required
integer [ 0 .. 65535 ]

The browser's screen width returned from the screen.width property.

screenHeight
required
integer [ 0 .. 65535 ]

The browser's screen height returned from the screen.height property.

timeZoneOffset
required
integer [ -1410 .. 1410 ]

The browser's time zone offset in minutes from UTC. A positive offset indicates the local time is behind UTC, and negative is ahead. Can find it with (new Date()).getTimezoneOffset() property.

object (Extra data)

Third party data used for risk scoring.

kountFraudSessionId
string [ 10 .. 32 ]

Alpha-numeric fraudSessionId as provided by the Kount SDK.

payPalMerchantSessionId
string [ 1 .. 64 ]

MerchantSessionID as generated by the PayPal Fraudnet SDK.

threatMetrixSessionId
string [ 1 .. 128 ] [a-zA-Z0-9_-]+

A temporary identifier that is unique to the visitor's session and passed to ThreatMetrix.

Responses
201

Setup transaction was created.

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

The resource ID. Defaults to UUID v4.

websiteId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

type
string

Transaction type.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Transaction status.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Transaction result.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

The transaction's amount.

currency
string = 3 characters

ISO 4217 alphabetic currency code.

purchaseAmount
number <double>

The amount actually purchased which may have differed from the originally requested amount in case of an adjustment.

purchaseCurrency
string = 3 characters

ISO 4217 alphabetic currency code.

requestAmount
number <double>

The amount in the payment request. If adjusted, the purchase amount and billing amount may vary from it.

requestCurrency
string = 3 characters

ISO 4217 alphabetic currency code.

parentTransactionId
string <= 50 characters

The resource ID. Defaults to UUID v4.

childTransactions
Array of strings (ResourceId)

The child transaction IDs.

invoiceIds
Array of strings (ResourceId)

The invoice IDs related to transaction.

subscriptionIds
Array of strings (ResourceId)

The orders IDs related to transaction's invoice(s).

planIds
Array of strings (ResourceId)

The plan IDs related to transaction's order(s).

isRebill
boolean
rebillNumber
integer

The transaction's rebill number.

object (InstrumentReference)
method
required
string (PaymentMethod)

The payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 155 more
paymentInstrumentId
string <= 50 characters

The resource ID. Defaults to UUID v4.

object

Billing address.

firstName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact first name.

lastName
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact last name.

organization
string or null <= 255 characters ^[\w\s\-\pL,.'&]+$

The contact organization.

address
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address.

address2
string or null <= 60 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact street address (second line).

city
string or null <= 45 characters ^[\w\s\-\pL,.']+$

The contact city.

region
string or null <= 45 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact region (state).

country
string or null <= 2 characters ^[A-Z]{2}$

The contact country ISO Alpha-2 code.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

The contact postal code.

Array of objects (ContactPhoneNumbers)

The list of phone numbers.

Array
label
required
string <= 45 characters

The phone label.

value
required
string <= 50 characters

The phone value.

primary
boolean

True if phone is primary.

Array of objects (ContactEmails)

The list of emails.

Array
label
required
string <= 45 characters

The email label.

value
required
string <email> <= 255 characters

The email value.

primary
boolean

True if email is primary.

dob
string or null <date>

The contact's date of birth in ISO-8601 format (yyyy-mm-dd).

jobTitle
string or null <= 255 characters ^[\w\s\-\/\pL,.#;:()']+$

The contact's job title.

hash
string <= 40 characters

A hash that can be used to compare multiple contacts for identical attribute values.

has3ds
boolean
object
server
string

3D Secure server name.

version
string

3D Secure version.

Enum: "1.0.2" "2.1.0" "2.2.0"
enrolled
string

Is the cardholder enrolled in 3D Secure.

Enum: "yes" "no" "invalid card/timeout" "unavailable"
authenticated
string

3D Secure authentication response status.

Enum: "yes" "no" "not applicable" "attempted"
liability
string
Enum: "protected" "not protected" "protected (attempt)"
flow
string

3D Secure 2 authentication flow.

Enum: "frictionless" "challenge"
isDowngraded
boolean
Default: false

If 3D Secure 2 was attempted but downgraded to 3D Secure 1.

redirectUrl
string <uri>

The URL to redirect the end-user when an offsite transaction is completed. Defaults to the website's configured URL.

retryNumber
integer

The position in the sequence of retries.

isRetry
boolean

True if this transaction is retry.

billingDescriptor
string

The billing descriptor that appears on the periodic billing statement. Commonly 12 or fewer characters for a credit card statement.

description
string <= 255 characters

The payment description.

requestId
string

The transaction's request ID. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

True if transaction has amount adjustment.

gatewayName
string

The payment gateway name.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 164 more
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).

processedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

approvalUrl
string <uri>

The URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

The session's token used for authentication. It would allow to visit created order, invoice and transaction.

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

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

post/payment-instruments/{id}/setup
Request samples
application/json
{
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "currency": "USD",
  • "amount": 97.97,
  • "billingAddress": {
    },
  • "redirectUrl": "http://example.com",
  • "riskMetadata": {
    }
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "websiteId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "type": "3ds-authentication",
  • "status": "completed",
  • "result": "abandoned",
  • "amount": 0,
  • "currency": "USD",
  • "purchaseAmount": 0,
  • "purchaseCurrency": "USD",
  • "requestAmount": 0,
  • "requestCurrency": "USD",
  • "parentTransactionId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "childTransactions": [
    ],
  • "invoiceIds": [
    ],
  • "subscriptionIds": [
    ],
  • "planIds": [
    ],
  • "isRebill": true,
  • "rebillNumber": 0,
  • "paymentInstrument": {
    },
  • "billingAddress": {
    },
  • "has3ds": true,
  • "3ds": {
    },
  • "redirectUrl": "http://example.com",
  • "retryNumber": 0,
  • "isRetry": true,
  • "billingDescriptor": "string",
  • "description": "string",
  • "requestId": "string",
  • "hasAmountAdjustment": true,
  • "gatewayName": "A1Gateway",
  • "customFields": {
    },
  • "processedTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "approvalUrl": "http://example.com",
  • "token": "string",
  • "_links": [
    ]
}