Payment Instruments

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Related Guides: Using Hosted Fields, Getting Started

Create a Payment Instrument

Create a Payment Instrument resource using a card or bank account.

  • The creation of Payment Instruments directly via Finix's API should only be done for testing purposes. You must use our hosted fields or the javascript client to remain out of PCI scope.
Request
Request Body schema: application/hal+json
Any of:
object

The address of the bank account or card owner.

expiration_month
integer

The expiration month of the card (e.g. 12 for December).

expiration_year
integer

The 4-digit expiration year of the card.

identity
string

The ID of the Identity used to create the Payment Instrument resource.

name
string

The name of the bank account or card owner.

number
string

The card or bank account number (no dashes in between numbers).

security_code
string

The 3-4 digit security code of the card (i.e. CVV code).

object

Key value pair for annotating custom meta data (e.g. order numbers).

third_party_token
string

Stringified token provided by Apple or Google. Required if using Apple or Google Pay.

type
string

Type of Payment Instrument.

Value: "PAYMENT_CARD"
Responses
201

Single Payment Instrument object

Response Schema: application/hal+json
Any of:
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object or null

Principal's personal home address. This field is used for Identity verification purposes.

address_verification
string

Additional address information that’s required to verify the identity of the merchant.

Enum: "POSTAL_CODE_AND_STREET_MATCH" "STREET_MATCH" "POSTAL_CODE_MATCH" "NO_ADDRESS" "NO_MATCH" "NOT_SUPPORTED" "UNKNOWN"
application
string

The ID of the Application resource the Payment Instrument was created under.

bin
string

Bank Identification number for the Payment Instrument.

brand
string

The brand of the card saved in the Payment Instrument.

Enum: "UNKNOWN" "DINERS_CLUB_INTERNATIONAL" "DANKORT" "MIR" "TROY" "UATP" "CHINA_T_UNION" "CHINA_UNION_PAY" "AMERICAN_EXPRESS" "VERVE" "RUPAY" "DISCOVER" "JCB" "MASTERCARD" "INTERPAYMENT" "INSTAPAYMENT" "MAESTRO" "VISA" "LANKAPAY" "DINERS_CLUB"
card_name
string or null

A custom name you can include to identify the card being used (e.g. Business Card).

card_type
string

The type of payment card saved in the Payment Instrument.

Enum: "CREDIT" "DEBIT" "HSA_FSA" "NON_RELOADABLE_PREPAID" "RELOADABLE_PREPAID" "UNKNOWN"
created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
expiration_month
integer [ 1 .. 12 ]

Expiration month (e.g. 12 for December).

expiration_year
integer >= 1

4-digit expiration year.

fast_funds_indicator
string

Details if Fast Funds is enabled for the card.

fingerprint
string

Unique ID that represents the tokenized card data.

id
string

The ID of the Payment Instrument.

identity
string

The ID of the Identity used to create the Payment Instrument resource.

instrument_type
string

The type of Payment Instrument.

Value: "PAYMENT_CARD"
issuer_country
string

Details what country the card was issued in:

  • USA: The card was issued inside the United States.
  • NON_USA: The card was issued outside of the United States.
  • UNKNOWN: Processor did not return an issuer country for this particular BIN.

  • Enum: "USA" "NON_USA" "UNKNOWN"
    last_four
    string

    Last four digits of the card or bank account number.

    name
    string or null

    The name of the bank account or card owner.

    online_gambing_block_indicator
    string

    Detailes if the card is enabled to receive push-payments for online gambling payouts.

    payload_type
    string
    Enum: "SOURCE" "DESTINATION"
    push_funds_block_indicator
    string

    Details if the card is enabled to receive push-to-card disbursements.

    security_code_verification
    string

    Details the results of the Card Verification Code check.

    Enum: "MATCHED" "UNKNOWN" "UNMATCHED"
    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    Type of Payment Instrument.

    Value: "PAYMENT_CARD"
    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    400

    Error

    401

    Authentication information is missing or invalid

    403

    Forbidden

    406

    Not Acceptable

    post/payment_instruments
    Request samples
    Response samples
    application/hal+json
    {}

    List Payment Instruments

    Retrieve a list of Payment Instruments.

    Request
    query Parameters
    account_last4
    string

    Filter by the last 4 digits of the account if available.

    Example: account_last4=9444
    account_routing_number
    string

    Filter by the account routing number if available.

    Example: account_routing_number=9444
    after_cursor
    string

    Return every resource created after the cursor value.

    application
    string

    Filter by Application ID.

    before_cursor
    string

    Return every resource created before the cursor value.

    bin
    string

    Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.

    Example: bin=489514
    created_at.gte
    string

    Filter where created_at is after the given date.

    Example: created_at.gte=created_at.gte=2019-06-15
    created_at.lte
    string

    Filter where created_at is before the given date.

    Example: created_at.lte=created_at.lte=2019-06-15
    expiration_month
    string

    Filter by the expiration month associated with the Payment Instrument if applicable. This filter only applies to payment cards.

    Example: expiration_month=1
    expiration_year
    string

    Filter by the 4 digit expiration year associated with the Payment Instrument if applicable. This filter only applies to payment cards.

    Example: expiration_year=2022
    last_four
    string

    Filter by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards.

    Example: last_four=0454
    limit
    integer

    The numbers of items to return.

    Example: limit=10
    name
    string

    Filter by the name.

    Example: name=fran%20lemke
    owner_identity_id
    string

    Filter by the owner id of the associated Identity.

    Example: owner_identity_id=IDcWwprrKrD6cSh225JWPri3
    type
    string

    Filter by the Payment Instrument type.

    Enum: "ALL" "BANK_ACCOUNT" "PAYMENT_CARD"
    Example: type=BANK_ACCOUNT
    Responses
    200

    List of Payment Instrument objects

    Response Schema: application/hal+json
    object

    List of Payment Instrument objects.

    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    object

    Details the page that's returned.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    406

    Not Acceptable

    get/payment_instruments
    Request samples
    curl https://finix.sandbox-payments-api.com/payment_instruments \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/hal+json
    {}

    Fetch a Payment Instrument

    Retrieve the details of a Payment Instrument.

    Request
    path Parameters
    payment_instrument_id
    required
    string

    ID of object

    Responses
    200

    Single Payment Instrument object

    Response Schema: application/hal+json
    Any of:
    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    object or null

    Principal's personal home address. This field is used for Identity verification purposes.

    address_verification
    string

    Additional address information that’s required to verify the identity of the merchant.

    Enum: "POSTAL_CODE_AND_STREET_MATCH" "STREET_MATCH" "POSTAL_CODE_MATCH" "NO_ADDRESS" "NO_MATCH" "NOT_SUPPORTED" "UNKNOWN"
    application
    string

    The ID of the Application resource the Payment Instrument was created under.

    bin
    string

    Bank Identification number for the Payment Instrument.

    brand
    string

    The brand of the card saved in the Payment Instrument.

    Enum: "UNKNOWN" "DINERS_CLUB_INTERNATIONAL" "DANKORT" "MIR" "TROY" "UATP" "CHINA_T_UNION" "CHINA_UNION_PAY" "AMERICAN_EXPRESS" "VERVE" "RUPAY" "DISCOVER" "JCB" "MASTERCARD" "INTERPAYMENT" "INSTAPAYMENT" "MAESTRO" "VISA" "LANKAPAY" "DINERS_CLUB"
    card_name
    string or null

    A custom name you can include to identify the card being used (e.g. Business Card).

    card_type
    string

    The type of payment card saved in the Payment Instrument.

    Enum: "CREDIT" "DEBIT" "HSA_FSA" "NON_RELOADABLE_PREPAID" "RELOADABLE_PREPAID" "UNKNOWN"
    created_at
    string <date-time>

    Timestamp of when the object was created.

    currency
    string

    ISO 4217 3 letter currency code.

    Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
    expiration_month
    integer [ 1 .. 12 ]

    Expiration month (e.g. 12 for December).

    expiration_year
    integer >= 1

    4-digit expiration year.

    fast_funds_indicator
    string

    Details if Fast Funds is enabled for the card.

    fingerprint
    string

    Unique ID that represents the tokenized card data.

    id
    string

    The ID of the Payment Instrument.

    identity
    string

    The ID of the Identity used to create the Payment Instrument resource.

    instrument_type
    string

    The type of Payment Instrument.

    Value: "PAYMENT_CARD"
    issuer_country
    string

    Details what country the card was issued in:

  • USA: The card was issued inside the United States.
  • NON_USA: The card was issued outside of the United States.
  • UNKNOWN: Processor did not return an issuer country for this particular BIN.

  • Enum: "USA" "NON_USA" "UNKNOWN"
    last_four
    string

    Last four digits of the card or bank account number.

    name
    string or null

    The name of the bank account or card owner.

    online_gambing_block_indicator
    string

    Detailes if the card is enabled to receive push-payments for online gambling payouts.

    payload_type
    string
    Enum: "SOURCE" "DESTINATION"
    push_funds_block_indicator
    string

    Details if the card is enabled to receive push-to-card disbursements.

    security_code_verification
    string

    Details the results of the Card Verification Code check.

    Enum: "MATCHED" "UNKNOWN" "UNMATCHED"
    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    Type of Payment Instrument.

    Value: "PAYMENT_CARD"
    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    422

    Invalid field

    get/payment_instruments/{payment_instrument_id}
    Request samples
    curl https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/hal+json
    {}

    Update a Payment Instrument

    Update a Payment Instrument.

    Request
    path Parameters
    payment_instrument_id
    required
    string

    ID of object

    Request Body schema: application/hal+json
    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    Responses
    200

    Single Payment Instrument object

    Response Schema: application/hal+json
    Any of:
    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    object or null

    Principal's personal home address. This field is used for Identity verification purposes.

    address_verification
    string

    Additional address information that’s required to verify the identity of the merchant.

    Enum: "POSTAL_CODE_AND_STREET_MATCH" "STREET_MATCH" "POSTAL_CODE_MATCH" "NO_ADDRESS" "NO_MATCH" "NOT_SUPPORTED" "UNKNOWN"
    application
    string

    The ID of the Application resource the Payment Instrument was created under.

    bin
    string

    Bank Identification number for the Payment Instrument.

    brand
    string

    The brand of the card saved in the Payment Instrument.

    Enum: "UNKNOWN" "DINERS_CLUB_INTERNATIONAL" "DANKORT" "MIR" "TROY" "UATP" "CHINA_T_UNION" "CHINA_UNION_PAY" "AMERICAN_EXPRESS" "VERVE" "RUPAY" "DISCOVER" "JCB" "MASTERCARD" "INTERPAYMENT" "INSTAPAYMENT" "MAESTRO" "VISA" "LANKAPAY" "DINERS_CLUB"
    card_name
    string or null

    A custom name you can include to identify the card being used (e.g. Business Card).

    card_type
    string

    The type of payment card saved in the Payment Instrument.

    Enum: "CREDIT" "DEBIT" "HSA_FSA" "NON_RELOADABLE_PREPAID" "RELOADABLE_PREPAID" "UNKNOWN"
    created_at
    string <date-time>

    Timestamp of when the object was created.

    currency
    string

    ISO 4217 3 letter currency code.

    Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
    expiration_month
    integer [ 1 .. 12 ]

    Expiration month (e.g. 12 for December).

    expiration_year
    integer >= 1

    4-digit expiration year.

    fast_funds_indicator
    string

    Details if Fast Funds is enabled for the card.

    fingerprint
    string

    Unique ID that represents the tokenized card data.

    id
    string

    The ID of the Payment Instrument.

    identity
    string

    The ID of the Identity used to create the Payment Instrument resource.

    instrument_type
    string

    The type of Payment Instrument.

    Value: "PAYMENT_CARD"
    issuer_country
    string

    Details what country the card was issued in:

  • USA: The card was issued inside the United States.
  • NON_USA: The card was issued outside of the United States.
  • UNKNOWN: Processor did not return an issuer country for this particular BIN.

  • Enum: "USA" "NON_USA" "UNKNOWN"
    last_four
    string

    Last four digits of the card or bank account number.

    name
    string or null

    The name of the bank account or card owner.

    online_gambing_block_indicator
    string

    Detailes if the card is enabled to receive push-payments for online gambling payouts.

    payload_type
    string
    Enum: "SOURCE" "DESTINATION"
    push_funds_block_indicator
    string

    Details if the card is enabled to receive push-to-card disbursements.

    security_code_verification
    string

    Details the results of the Card Verification Code check.

    Enum: "MATCHED" "UNKNOWN" "UNMATCHED"
    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    type
    string

    Type of Payment Instrument.

    Value: "PAYMENT_CARD"
    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    put/payment_instruments/{payment_instrument_id}
    Request samples
    Response samples
    application/hal+json
    {}

    List Payment Instrument Updates

    List the updates on a Payment Instrument.

    When using the account updater, Payment Instrument details that are updated are represented by an Update.

    Request
    path Parameters
    payment_instrument_id
    required
    string

    ID of Payment Instrument object.

    query Parameters
    limit
    integer <int64>

    The number of entries to return.

    offset
    integer <int64>

    The number of items to skip before starting to collect the result set.

    pageSize
    integer <int64>

    The size of the page.

    Responses
    200

    List of Update objects

    Response Schema: application/hal+json
    object

    List of updates for a Payment Instrument.

    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    object
    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    get/payment_instruments/{payment_instrument_id}/updates
    Request samples
    curl https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/updates \
      -H "Content-Type: application/vnd.json+api" \
      -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    
    Response samples
    application/hal+json
    {}

    Verify a Payment Instrument

    Verify a Payment Instrument to determine if it's eligible for Push To Card transactions.

    • Only verify Payment Instruments for Push To Card customers.
    Request
    path Parameters
    payment_instrument_id
    required
    string

    ID of Payment Instrument object.

    Request Body schema: application/hal+json
    identity
    string

    ID of the Identity resource associated with the Merchant.

    merchant
    string

    The ID of the Merchant.

    processor
    string or null

    Set the acquiring processor. Avalible values include:

    • DUMMY_V1
    • LITLE_V1
    • MASTERCARD_V1
    • VISA_V1
    • NMI_V1
    • VANTIV_V1
    Use DUMMY_V1 or null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    Responses
    201

    Single Verification object

    Response Schema: application/hal+json
    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    application
    string

    ID of the Application the Merchant was created under.

    created_at
    string <date-time>

    Timestamp of when the object was created.

    id
    string

    The ID of the Verification attempt (begins with VIXXX).

    identity
    string or null

    ID of the Identity that created the Merchant.

    merchant
    string or null

    ID of the Merchant resource.

    merchant_identity
    string or null

    ID of the Identity associated with the Merchant.

    messages
    Array of objects

    Provides additional details about the verification (e.g why it failed). This field is usually null.

    payment_instrument
    string or null

    The Payment Instrument that'll be used to settle the Merchant's processed funds.

    processor
    string

    Name of the verification processor.

    (Raw (object or null)) or (Raw (string or null))

    Raw response from the processor.

    state
    string

    The status of the Verification request.

    Enum: "PENDING" "SUCCEEDED" "FAILED"
    object

    Key value pair for annotating custom meta data (e.g. order numbers).

    trace_id
    string

    Trace ID of the Verification. The processor sends back the trace_id so you can track the verification end-to-end.

    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    400

    Error

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    post/payment_instruments/{payment_instrument_id}/verifications
    Request samples
    Response samples
    application/hal+json
    {}

    Create an Apple Pay Session

    Create an apple_pay_session to process Apple Pay transactions on the web.

    To create an Apple Pay Session, pass the unique validation_url (provided by Apple) while creating an apple_pay_sessions resource. Finix returns a merchantSession object that you can use to create a payment. For more information, see Apple Pay.

    Request
    Request Body schema: application/hal+json
    display_name
    string

    This will be the merchant name shown to users when making a purchase via Apple Pay.

    domain
    string

    The domain (or website) where the buyer is initiating the payment.

    merchant_identity
    string

    The merchant_identity_id used when registering the business with Apple Pay through our registration API.

    validation_url
    string

    A unique validation URL that will be provided by the Apple SDK front-end for every payment.

    Responses
    200

    Single apple_pay_session object

    Response Schema: application/hal+json
    object

    For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

    created_at
    string <date-time>

    Timestamp of when the object was created.

    id
    string

    The ID of the apple_pay_session resource.

    session_details
    string

    Details about the apple_pay_session that was created.

    updated_at
    string <date-time>

    Timestamp of when the object was last updated.

    401

    Authentication information is missing or invalid

    403

    Forbidden

    404

    Object does not exist

    406

    Not Acceptable

    post/apple_pay_sessions
    Request samples
    Response samples
    application/hal+json
    {
    • "id": "APPLEPAYSESSION_xxx",
    • "created_at": "2021-11-22T23:58:19.50Z",
    • "updated_at": "2021-11-22T23:58:19.50Z",
    • "session_details": "{\"epochTimestamp\":1640213041060,\"expiresAt\":1640216641060,\"merchantSessionIdentifier\":\"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"a5ee8554\",\"merchantIdentifier\":\"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"domainName\":\"tj.ngrok.io\",\"displayName\":\"Christmas Shopping\",\"signature\":\"...\",\"operationalAnalyticsIdentifier\":\"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"retries\":0}",
    }