Create a payment instrument

Request

Creates a payment instrument. If the payment card, bank account, or alternative payment instrument already exists it is updated.
Security
SecretApiKey or JWT
Bodyapplication/jsonrequired
PaymentInstrument resource.
One of:
customerIdstring, <= 50 characters(CustomerId)required
ID of the customer resource.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
tokenstringrequired
ID of the payment token.
customFieldsobject(ResourceCustomFields)

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

Default:{}
Example:
{
  "foo": "bar"
}
useAsBackupboolean(UseAsBackup)
Specifies if this payment instrument can be used as a backup for invoice payment retries.
Default:false
curl -i -X POST \
  https://www.rebilly.com/_mock/catalog/all/payment-instruments \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
    "token": "string",
    "customFields": {
      "foo": "bar"
    },
    "useAsBackup": false
  }'

Responses

Payment instrument created.
Headers
Locationstring, (uri)
Location of the related resource.
Example:"https://api.rebilly.com/example"
Rate-Limit-Limitinteger

Maximum number of requests available at one time for this rate limit. For more information, see Rate limits.

Example:500
Rate-Limit-Remaininginteger

Number of requests still available for this rate limit. For more information, see Rate limits.

Example:499
Bodyapplication/json
idstring, <= 50 charactersread-only
ID of the payment instrument.
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
customerIdstring, <= 50 characters(CustomerId)
ID of the customer resource.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
methodstringrequired
Method of payment instrument.
Value:"payment-card"
Discriminator
statusstring

Status of the payment instrument. An active status means that a payment instrument has been used at least once for an approved transaction. To remove an instrument from use, set this value to deactivated.

For more information, see POST /payment-instruments/{id}/deactivation.

Enum:"active""inactive""expired""deactivated""verification-needed"
fingerprintstringread-only

Unique value that is used to identify the payment instrument. This value is generated from the bin and the last4 values. This value contains alphanumeric characters.

binstring, (bin)read-only

Bank Identification Number (BIN) of the payment card. This value is the same as the first 6 digits of the associated Primary Account Number (PAN).

last4stringread-only

Last 4 digits of the associated Primary Account Number (PAN).

fpanLast4string or nullread-only

Last 4 digits of the Funding Primary Account Number (FPAN) of the payment card. This value is only present for payment cards created from digital wallet tokens, where the FPAN is the physical card number visible to the cardholder, as opposed to the Device Primary Account Number (DPAN) used in the digital wallet transaction.

expYearinteger
Expiration year of the payment card.
expMonthinteger
Expiration month of the payment card.
brandstring(PaymentCardBrand)read-only
Brand of payment card.
Enum:"Visa""MasterCard""American Express""Discover""Maestro""Solo""Electron""JCB""Voyager""Diners Club"
bankCountrystring or nullread-only
Bank country of the payment instrument.
bankNamestringread-only
Bank name of the payment instrument.
isPayoutablebooleanread-only

Specifies if payouts are supported for cards with this BIN. Defaults to true. This value is false if the BIN does not support payouts.

billingAddressobject(ContactObject)
Contact's billing address.
useAsBackupboolean(UseAsBackup)
Specifies if this payment instrument can be used as a backup for invoice payment retries.
Default:false
billingPortalUrlstringread-only
URL of the billing portal where the card can be updated.
createdTimestring, (date-time)(CreatedTime)read-only
Date and time when the resource is created. This value is set automatically when the resource is created.
updatedTimestring, (date-time)(UpdatedTime)read-only
Date and time when the resource is updated. This value is set automatically when the resource is updated.
lastPaymentTimestring or null, (date-time)(LastPaymentTime)read-only

Date and time of the last approved payment. Payments are the result of sale or capture transactions.

customFieldsobject(ResourceCustomFields)

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

Default:{}
Example:
{
  "foo": "bar"
}
stickyGatewayAccountIdstring or nullread-only

ID of the sticky gateway account. All future payments are processed by this gateway account.

For more information, see Gateway routing.

expirationReminderTimestring or null, (date-time)read-only
Date and time when an expiration reminder event is triggered.
expirationReminderNumberinteger or nullread-only
Number of expiration reminder events that have triggered.
referenceDataobject
Payment instrument reference data.
Example:
{
  "gatewayTransactionId": "GAT123"
}
digitalWalletstring or nullread-only
Digital wallet type.
Enum:"Apple Pay""Google Pay""Samsung Pay"null
riskMetadataRisk metadata (object) or null
One of:
Risk metadata used for 3D Secure and risk scoring.
revisionintegerread-only
Number of times the payment instrument data has been modified. Use this value when analyzing webhook data to determine if a change must take precedence over the current representation.
_linksArray of objectsread-only
Related links.
_embeddedobjectread-only

Embedded objects that are requested by the expand query parameter.

Response
{
  "id": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
  "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "method": "payment-card",
  "status": "active",
  "fingerprint": "string",
  "bin": "string",
  "last4": "string",
  "fpanLast4": "string",
  "expYear": 0,
  "expMonth": 0,
  "brand": "Visa",
  "bankCountry": "string",
  "bankName": "string",
  "isPayoutable": true,
  "billingAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": "Rebilly",
    "address": "36 Craven St",
    "address2": "string",
    "city": "Austin",
    "region": "Texas",
    "country": "GB",
    "postalCode": "WC2N 5NF",
    "phoneNumbers": [ … ],
    "emails": [ … ],
    "dob": "1980-04-01",
    "jobTitle": "CEO",
    "hash": "056ae6d97c788b9e98b049ebafd7b229bf852221"
  },
  "useAsBackup": false,
  "billingPortalUrl": "string",
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "lastPaymentTime": "2019-08-24T14:15:22Z",
  "customFields": {
    "foo": "bar"
  },
  "stickyGatewayAccountId": "string",
  "expirationReminderTime": "2019-08-24T14:15:22Z",
  "expirationReminderNumber": 0,
  "referenceData": {
    "gatewayTransactionId": "GAT123"
  },
  "digitalWallet": "Apple Pay",
  "riskMetadata": {
    "ipAddress": "93.92.91.90",
    "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
    "httpHeaders": { … },
    "browserData": { … },
    "extraData": { … },
    "isProxy": true,
    "isVpn": true,
    "isTor": true,
    "isHosting": true,
    "hostingName": "string",
    "isp": "string",
    "country": "US",
    "region": "NY",
    "city": "New York",
    "latitude": 0,
    "longitude": 0,
    "postalCode": "string",
    "timeZone": "America/New_York",
    "accuracyRadius": 0,
    "distance": 0,
    "hasMismatchedBillingAddressCountry": true,
    "hasMismatchedBankCountry": true,
    "hasMismatchedTimeZone": true,
    "hasMismatchedHolderName": true,
    "hasFakeName": true,
    "isHighRiskCountry": true,
    "paymentInstrumentVelocity": 0,
    "declinedPaymentInstrumentVelocity": 0,
    "deviceVelocity": 0,
    "ipVelocity": 0,
    "emailVelocity": 0,
    "billingAddressVelocity": 0,
    "paymentInstrumentApprovedTransactionCount": 0,
    "score": 0
  },
  "revision": 0,
  "_links": [
    { … }
  ],
  "_embedded": {
    "customer": {}
  }
}