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