Sign in

v1

latestOpenAPI 3.1.0Payrails GmbH2026-07-2614905.7 MB
Instruments

Create an instrument

Create a payment instrument.

post/payment/instruments

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

holderIdstring uuid

Unique identifier of the Holder in Payrails. At least one of holderId or holderReference values have to be provided in the request.

holderReferencestring

Merchant-provided reference for the transaction counterparty, i.e. the paying consumer. At least one of holderReference or holderId values have to be provided in the request.

paymentMethod'googlePay' | 'applePay' | 'card' | 'payPal' | 'bankAccount' required

Represents the payment method type.

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

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

descriptionstring

Human-friendly description of the Instrument.

merchantReferencestring

Merchant-provided reference for the instrument.

networkTransactionReferencestring

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

storeInstrumentboolean

True if the holder wants to store the instrument for future use when payment is completed.

defaultboolean nullable

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

workspaceIdstring uuid

Workspace identifier. When a merchant has multiple network token provider configs, this determines which workspace-scoped config is used for network token provisioning.

provisionNetworkTokenboolean

True if the merchant wants to provision a network token for this instrument.

Example request

{
  "description": "Main card, mom's card, company card",
  "data": {
    "bin": "416598",
    "binLookup": {
      "bin": "416598"
    }
  }
}

Response

Created.

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"
    }
  }
}