POST /payment_instruments
GET /payment_instruments
GET /payment_instruments/{id}
PUT /payment_instrument/{id}
POST /payment_instruments/{payment_instrument_id}/updates
POST /payment_instruments/{payment_instrument_id}/verifications
POST /apple_pay_session
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
resource using a card or bank account.
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.Single Payment Instrument object
Error
Authentication information is missing or invalid
Forbidden
Not Acceptable
{- "id": "PI8uU6wfi6hqBoWmzm9L4F2b",
- "created_at": "2022-10-11T01:42:22.32Z",
- "updated_at": "2022-10-11T01:42:22.32Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "created_via": "API",
- "currency": "USD",
- "enabled": true,
- "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
- "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
- "instrument_type": "PAYMENT_CARD",
- "address": {
- "line1": "900 Metro Center Blv",
- "line2": null,
- "city": "San Francisco",
- "region": "CA",
- "postal_code": "94404",
- "country": "USA"
}, - "address_verification": "UNKNOWN",
- "bin": "520082",
- "brand": "MASTERCARD",
- "card_type": "DEBIT",
- "expiration_month": 12,
- "expiration_year": 2029,
- "issuer_country": "NON_USA",
- "last_four": "8210",
- "name": "John Smith",
- "security_code_verification": "UNKNOWN",
- "tags": {
- "card_name": "Business Card"
}, - "type": "PAYMENT_CARD",
- "_links": {
- "self": {
}, - "authorizations": {
}, - "transfers": {
}, - "verifications": {
}, - "application": {
}, - "updates": {
}
}
}
Retrieve a list of Payment Instruments
.
List of Payment Instrument objects
Authentication information is missing or invalid
Forbidden
Not Acceptable
curl https://finix.sandbox-payments-api.com/payment_instruments \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "payment_instruments": [
- {
- "id": "PI3AbkuRR1JbT5kPiGQCXvD9",
- "created_at": "2022-10-11T01:42:53.29Z",
- "updated_at": "2022-10-11T01:42:53.29Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "created_via": "API",
- "currency": "USD",
- "enabled": true,
- "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "instrument_type": "BANK_ACCOUNT",
- "account_type": "SAVINGS",
- "bank_account_validation_check": "NOT_ATTEMPTED",
- "bank_code": "123123123",
- "country": "USA",
- "masked_account_number": "XXXXX3123",
- "name": "John",
- "tags": {
- "Bank Account": "Company Account"
}, - "type": "BANK_ACCOUNT",
- "_links": {
- "self": {
}, - "authorizations": {
}, - "transfers": {
}, - "verifications": {
}, - "application": {
},
}
}, - {
- "id": "PIrb1DcGz1qjThotDJ5KURpv",
- "created_at": "2022-10-06T20:23:38.74Z",
- "updated_at": "2022-10-06T20:23:38.74Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "created_via": "API",
- "currency": "USD",
- "enabled": true,
- "fingerprint": "FPRtvYkgcwLUdjq7B4AgxKfmr",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "instrument_type": "BANK_ACCOUNT",
- "account_type": "SAVINGS",
- "bank_account_validation_check": "NOT_ATTEMPTED",
- "bank_code": "666666666",
- "country": "USA",
- "masked_account_number": "XXXXX3123",
- "name": "test_python",
- "tags": {
- "bank_account": "Test Python Account"
}, - "type": "BANK_ACCOUNT",
- "_links": {
- "self": {
}, - "authorizations": {
}, - "transfers": {
}, - "verifications": {
}, - "application": {
},
}
}
]
}, - "_links": {
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 14679
}
}
Retrieve the details of a Payment Instrument
.
Single Payment Instrument object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
Invalid field
curl https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "id": "PI8uU6wfi6hqBoWmzm9L4F2b",
- "created_at": "2022-10-11T01:42:22.32Z",
- "updated_at": "2022-10-11T01:42:22.32Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "created_via": "API",
- "currency": "USD",
- "enabled": true,
- "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
- "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
- "instrument_type": "PAYMENT_CARD",
- "address": {
- "line1": "900 Metro Center Blv",
- "line2": null,
- "city": "San Francisco",
- "region": "CA",
- "postal_code": "94404",
- "country": "USA"
}, - "address_verification": "UNKNOWN",
- "bin": "520082",
- "brand": "MASTERCARD",
- "card_type": "DEBIT",
- "expiration_month": 12,
- "expiration_year": 2029,
- "issuer_country": "NON_USA",
- "last_four": "8210",
- "name": "John Smith",
- "security_code_verification": "UNKNOWN",
- "tags": {
- "card_name": "Business Card"
}, - "type": "PAYMENT_CARD",
- "_links": {
- "self": {
}, - "authorizations": {
}, - "transfers": {
}, - "verifications": {
}, - "application": {
}, - "updates": {
}
}
}
Update a Payment Instrument
to:
instrument_type
:PAYMENT_CARD only).instrument_type
:PAYMENT_CARD only).Payment Instrument
resource so it can't be used in requests.tags
.Single Payment Instrument object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
{- "id": "PI8uU6wfi6hqBoWmzm9L4F2b",
- "created_at": "2022-10-11T01:42:22.32Z",
- "updated_at": "2022-10-11T01:42:22.32Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "created_via": "API",
- "currency": "USD",
- "enabled": true,
- "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
- "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
- "instrument_type": "PAYMENT_CARD",
- "address": {
- "line1": "900 Metro Center Blv",
- "line2": null,
- "city": "San Francisco",
- "region": "CA",
- "postal_code": "94404",
- "country": "USA"
}, - "address_verification": "UNKNOWN",
- "bin": "520082",
- "brand": "MASTERCARD",
- "card_type": "DEBIT",
- "expiration_month": 12,
- "expiration_year": 2029,
- "issuer_country": "NON_USA",
- "last_four": "8210",
- "name": "John Smith",
- "security_code_verification": "UNKNOWN",
- "tags": {
- "card_name": "Business Card"
}, - "type": "PAYMENT_CARD",
- "_links": {
- "self": {
}, - "authorizations": {
}, - "transfers": {
}, - "verifications": {
}, - "application": {
}, - "updates": {
}
}
}
Verify a Payment Instrument
to determine if it's eligible for Push To Card transactions.
Payment Instruments
for Push To Card customers.identity | string ID of the |
merchant | string The ID of the |
tags | object or null Include up to 50
(e.g., |
processor | string or null Set the acquiring processor. Avalible values include:
|
Single Verification object
Error
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/verifications \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d ' { "identity": "ID2CGJmjqyYaQAu6qyuvGeWK", "merchant": "MUgWbPVvtKbzjKNNGKqdQYV7", "tags": { "card_name": "Business_Card" } }'
{- "id": "VIvZKP8XKzxyJaxJsfAEHbw6",
- "created_at": "2022-10-11T00:46:48.68Z",
- "updated_at": "2022-10-11T00:46:48.72Z",
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "identity": null,
- "merchant": "MUgWbPVvtKbzjKNNGKqdQYV7",
- "merchant_identity": "ID2CGJmjqyYaQAu6qyuvGeWK",
- "messages": [ ],
- "payment_instrument": null,
- "processor": "DUMMY_V1",
- "raw": null,
- "state": "PENDING",
- "tags": {
- "card_name": "Business_Card"
}, - "trace_id": "a7355d05-95b0-4b44-938d-bf0a99f19c17",
- "_links": {
- "application": {
},
}
}
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.
Single apple_pay_session object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/apple_pay_sessions \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d ' { "display_name": "Finix Test Merchant", "domain": "www.finixtestmerchant.com", "merchant_identity": "IDmULj61C8ke6Y7qQiKENJ7", "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession" }'
{- "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}",
- "_links": {
}
}