Card Present Integration

The card present integration allows you to gateway card present transactions. With a quick and easy setup process, you'll be able to use point of sale devices to accept in-person payments. The card present integration also gives you the ability to unify in-person and online transactions on a single platform. To learn more about the card present integration and to be given access please contact bd@finixpayments.com.

Step 1: Provision Merchant with triPOS

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "processor": "VANTIV_V1",
            "gateway": "TRIPOS_CLOUD_V1"
        }'

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID/merchants

URL Parameters

Parameter Description
:IDENTITY_ID ID of the Identity

Request Arguments

Field Type Description
processor string, required Name of the processor
gateway string, required Name of the gateway
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}

Step 2: Create Device

Copy
Copied
curl https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/devices \
        -H "Content-Type: application/vnd.json+api" \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
      {
        "name": "Finix  triPOS #1",
        "model": "MX915",
        "description": "Mike Jones",
        "configuration": {
          "allow_debit": true,
          "prompt_signature": "NEVER"
        }
      }'

HTTP Request

POST https://finix.sandbox-payments-api.com/merchants/:MERCHANT_ID/devices

URL Parameters

Field Type Description
:MERCHANT_ID string, required ID of Device

Request Arguments

Field Type Description
model string, required Please select one of the following values which will let Finix know the type of device being used: MX915
name string, required Name of device
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
description string, optional Additional information about device (e.g. self serving terminal)

Configuration Arguments

Field Type Description
allow_debit boolean, optional Sets whether device will allow debit by default or not (defaults to true)
prompt_signature string, optional Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT
check_for_duplicate_transactions boolean, optional Sets whether the device will check for duplicate transactions
prompt_amount_confirmation boolean, optional Sets whether or not to make card holder confirm the amount they will pay (defaults is true)
signature_threshold_amount integer, optional Threshold set for when to prompt a signature prompt_signature is set to AMOUNT (defaults to 0)
prompt_manual_entry boolean, optional Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix  triPOS #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : null,
  "idle_message" : null,
  "enabled" : false,
  "device_config_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "created_at" : "2019-03-01T01:07:17.015",
  "updated_at" : "2019-03-01T01:07:17.022",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "activations" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf/activations"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 3: Activate Device

Copy
Copied
curl https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf \
  -H "Content-Type: application/vnd.json+api" \
  -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
  -X PUT \
  -d '
    {
      "activation_code": "C887298",
      "action": "ACTIVATE"
    }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/devices/:DEVICE_ID

URL Parameters

Field Type Description
:DEVICE_ID string, required ID of Device

Request Arguments

Field Type Description
action string, required The action parameter must include ACTIVATE for to enable device
activation_code string, required Input the code that's displayed on the device screen
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
{
  "id" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "merchant" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "name" : "Finix Tripos #1",
  "model" : "MX915",
  "description" : "Mike Jones",
  "serial_number" : "262-410-025",
  "idle_message" : null,
  "enabled" : true,
  "tags" : { },
  "created_at" : "2019-03-01T02:27:20.366",
  "updated_at" : "2019-03-11T23:19:44.378",
  "configuration_details" : {
    "allow_debit" : true,
    "check_for_duplicate_transactions" : true,
    "prompt_amount_confirmation" : true,
    "prompt_manual_entry" : false,
    "prompt_signature" : "NEVER",
    "signature_threshold_amount" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}

Step 4: Authorization with EMV card

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -d '
   {
     "device": "DVf2H8sh4LZZC52GTUrwCPPf",
     "tags": {
       "order_number": "chris123transfer"
     },
     "currency": "USD",
     "amount": 150,
     "operation_key": "CARD_PRESENT_AUTHORIZATION"
   }'

HTTP Request

POST https://finix.sandbox-payments-api.com/authorizations

Request Arguments

Field Type Description
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
device string, required The ID of the activated device
amount integer, required Amount of sale
currency string, required Currency of sale
operation_key string, required Describes the operation to be performed in the transaction

Configuration Arguments

allow_debit | boolean, optional | Sets whether device will allow debit by default or not (defaults to true) prompt_signature | string, optional | Sets whether device will prompt the card holder for a signature by default or not, AMOUNT is used in conjuction with signature_threshold_amount so that when the threshold is reached the signature form appears on device screen (defaults to always). Options are: ALWAYS, NEVER, AMOUNT check_for_duplicate_transactions | boolean, optional | Sets whether the device will check for duplicate transactions signature_threshold_amount | integer, optional | Threshold set for when to prompt a signature if device_configuration#prompt_signature is set to AMOUNT (defaults to 0) prompt_manual_entry | boolean, optional | Sets whether or not the default card input method will be keyed in manual entry or not (defaults to false)

{
  "id" : "TReEok8811pDqsR1BbxZLbw1",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "trace_id" : "FNXmEM7d6ns8LMMzt61AD8TrR",
  "currency" : "USD",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "source" : "PIcW77CfRyBUWJhA231TWXWf",
  "destination" : null,
  "ready_to_settle_at" : null,
  "fee" : 0,
  "statement_descriptor" : "FIN*GOLDS GYM",
  "type" : "DEBIT",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : {
    "emv_data" : {
      "application_identifier" : "A0000000031010",
      "application_label" : "Visa Credit",
      "application_preferred_name" : null,
      "application_transaction_counter" : "004F",
      "cryptogram" : "TC F8C706E8A0368D15",
      "issuer_code_table_index" : null,
      "pin_verified" : false
    },
    "masked_account_number" : "************7564",
    "name" : "AARON/CHRISTOPHER W ",
    "brand" : "VISA",
    "entry_mode" : "CHIP_ENTRY",
    "payment_type" : "CREDIT",
    "approval_code" : "000036"
  },
  "created_at" : "2019-03-11T23:36:42.03Z",
  "updated_at" : "2019-03-11T23:36:57.09Z",
  "idempotency_id" : null,
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "subtype" : "API",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/payment_instruments"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TReEok8811pDqsR1BbxZLbw1/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIcW77CfRyBUWJhA231TWXWf"
    }
  }

Step 5: Capture Authorization

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma \
   -H "Content-Type: application/vnd.json+api" \
   -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
   -X PUT \
   -d '
     {
         "capture_amount": 150
     }'

HTTP Request

PUT https://finix.sandbox-payments-api.com/authorizations/:AUTHORIZATION_ID

URL Parameters

Field Type Description
AUTHORIZATION_ID string, required ID of Device

Request Arguments

Field Type Description
capture_amount integer, required The amount of the Authorization you would like to capture in cents.
{
  "id" : "AUuCfRve8QG6G1wnPCReiLma",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "amount" : 150,
  "tags" : {
    "order_number" : "chris123transfer"
  },
  "state" : "SUCCEEDED",
  "currency" : "USD",
  "transfer" : "TRjiUo5CXLmaJp4k9PL7iP8z",
  "messages" : [ ],
  "raw" : null,
  "card_present_details" : null,
  "created_at" : "2019-03-01T03:42:13.59Z",
  "updated_at" : "2019-03-01T03:49:28.67Z",
  "trace_id" : "957ce193-b4e4-4a39-88e2-d88a019982d2",
  "source" : "PIjnHHLBZvRu6GPEZdFt7E2q",
  "merchant_identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "device" : "DVf2H8sh4LZZC52GTUrwCPPf",
  "is_void" : false,
  "expires_at" : "2019-03-08T03:42:13.59Z",
  "idempotency_id" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/authorizations/AUuCfRve8QG6G1wnPCReiLma"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "transfer" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRjiUo5CXLmaJp4k9PL7iP8z"
    },
    "device" : {
      "href" : "https://finix.sandbox-payments-api.com/devices/DVf2H8sh4LZZC52GTUrwCPPf"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    }
  }
}