Sign in

v1

latestOpenAPI 3.1.0Payrails GmbH2026-07-2614905.7 MB
Instruments

Update an instrument

Update an instrument.

patch/payment/instruments/{instrumentId}

Path parameters

instrumentIdstring uuid required

Identifier of the resource in Payrails.

Headers

x-idempotency-keystring uuid required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Request body

status'enabled' | 'disabled'

New status of the Instrument. If you want to change to "deleted", you should use the DELETE endpoint instead. Also, note that some status are internal and cannot be changed via API, e.g. transient, etc. Status update requests can also be rejected if an instrument status cannot be changed to the desired one, e.g. deleted instruments.

networkTransactionReferencestring

Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID.

merchantReferencestring

Merchant-provided reference for the instrument.

paymentMethod'applePay' | 'card' | 'googlePay' | 'payPal'

New payment method of the instrument. Only the methods supporting instruments are accepted.

defaultboolean nullable

True if the holder wants to make this instrument as default.

Response

Success.

idstring uuid required

Id of the instrument.

createdAtstring date-time required

Date and time when the Instrument was created in Payrails.

updatedAtstring date-time required

When the Instrument was last updated.

holderIdstring uuid required

Unique identifier of the Holder in Payrails.

paymentMethod'alexBankMa7fazty' | 'applePay' | 'audi2pay' | 'bankAccount' | 'card' | 'cibSmartWallet' | 'easypaisa' | 'etisalatCash' | 'fawryMobileWallet' | 'fawryPay' | 'googlePay' | 'jazzCash' | 'nbePhoneCash' | 'orangeCash' | 'payPal' | 'qnbEWallet' | 'weCash' | 'genericRedirect' | 'alfa' | 'konnect' | 'eftPro' | 'netBanking' | 'upi' | 'cashFreeWallet' | 'paytmWallet' | 'phonePe' required

Represents the payment method type.

status'created' | 'deleted' | 'enabled' | 'disabled' | 'transient' required

Status of the instrument.

displayNamestring

Instrument name suitable for display.

descriptionstring

Description of the instrument.

defaultboolean nullable

True if this instrument is set as default for the holder.

merchantReferencestring

Merchant-provided reference for the instrument.

fingerprintstring

System-wide unique identifier of the Instrument. If two Holders have the same instrument stored, this value will be the same for both, but the instrument and token IDs will be different. Cannot be used for payments, should only be used for analytics and fraud prevention.

futureUsage'Subscription' | 'CardOnFile' | 'UnscheduledCardOnFile'

Represents the future usage to define the payment flows that the stored instrument will be used for.

networkTransactionReferencestring

Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID.

Example response

{
  "data": {
    "bin": "416598",
    "binLookup": {
      "bin": "416598"
    }
  }
}