Priority gateway guide

Adding a Priority Payment Systems gateway

To add a Priority Payment Systems gateway you just need to supply your Priority Payment Systems API key, secret, and merchant id:

curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
  <gateway_type>priority</gateway_type>
  <api_key>Your API key</api_key>
  <secret>Your secret</secret>
  <merchant_id>Your merchant ID</merchant_id>
</gateway>'
<gateway>
  <token>ODeJhtBXEOysbYxhqdvfsr9at8G</token>
  <gateway_type>priority</gateway_type>
  <name>Priority</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <merchant_id>Your merchant ID</merchant_id>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
  </characteristics>
  <credentials>
    <credential>
      <name>merchant_id</name>
      <value>Your merchant ID</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>source</gateway_specific_field>
    <gateway_specific_field>invoice</gateway_specific_field>
    <gateway_specific_field>replay_id</gateway_specific_field>
    <gateway_specific_field>ship_amount</gateway_specific_field>
    <gateway_specific_field>ship_to_country</gateway_specific_field>
    <gateway_specific_field>ship_to_zip</gateway_specific_field>
    <gateway_specific_field>is_auth</gateway_specific_field>
    <gateway_specific_field>tax_exempt</gateway_specific_field>
    <gateway_specific_field>payment_type</gateway_specific_field>
    <gateway_specific_field>tender_type</gateway_specific_field>
    <gateway_specific_field>purchases</gateway_specific_field>
    <gateway_specific_field>pos_data</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2022-04-20T15:29:52Z</created_at>
  <updated_at type="dateTime">2022-04-20T15:29:52Z</updated_at>
</gateway>

The billing street address and zip code are required for all transactions.

Gateway specific fields

Spreedly supports the following gateway specific fields when transacting with a Priority Payment Systems gateway.

  • invoice
  • source
  • replay_id
  • ship_amount
  • ship_to_country
  • ship_to_zip
  • is_auth
  • tax_exempt
  • payment_type
  • tender_type
  • tax
  • customer_code
  • customer_name
  • vat_amount
  • vat_rate
  • duty_amount
  • memo
  • source_zip
  • purchases
    • name
    • description
    • code
    • unit_of_measure
    • unit_price
    • quantity
    • tax_rate
    • tax_amount
    • discount_rate
    • discount_amount
    • extended_amount
    • line_item_id
  • pos_data
    • cardholder_presence
    • device_attendance
    • device_input_capability
    • device_location
    • pan_capture_method
  • partial_approval_support
  • pin_capture_capability
  • channel

The following describes the purpose, usage, or possible values of select GSFs that are available:

  • source Possible values are API, QuickPay, Recurring, Link2Pay, and Terminal
  • replay_id Used to uniquely identify a purchase or authorize request. If supplied the gateway will check for a transaction that matches the identifier. If found they will return an identical response of the original request. Read more about replay_id in the gateway’s documentation.
  • purchases Accepts an array containing one or more purchase items. Each purchase item may include any or all of the subfields listed above.
  • pos_data Accepts an object containing one or more of the subfields listed above. If no value is provided for a given subfield, a default value will be added. For a list of acceptable values for the pos_data subfields, please see consult the gateway’s documentation.
  • channel Identifies the channel a stored credential transaction is made on. Possible values are Moto and Ecom. Used together with stored_credential_initiator and stored_credential_reason_type to send Priority's card-on-file posData. See Stored credentials below.
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
  <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
  <amount>100</amount>
  <currency_code>USD</currency_code>
  <gateway_specific_fields>
    <priority>
      <source>Terminal</source>
      <invoice>123</invoice>
      <replay_id>8765</replay_id>
      <ship_amount>1</ship_amount>
      <ship_to_country>USA</ship_to_country>
      <ship_to_zip>27703</ship_to_zip>
      <source_zip>09873</source_zip>
      <customer_code>CUST98765</customer_code>
      <customer_name>testEnterprise</customer_name>
      <tax>0.03</tax>
      <vat_amount>0.02</vat_amount>
      <vat_rate>0.01</vat_rate>
      <duty_amount>0.03</duty_amount>
      <memo>priority</memo>
      <is_auth>true</is_auth>
      <tax_exempt>true</tax_exempt>
      <payment_type>Sale</payment_type>
      <tender_type>Card</tender_type>
      <purchases>
        <name>purchase name</name>
        <description>purchase description</description>
        <code>123</code>
        <unit_of_measure>unit</unit_of_measure>
        <unit_price>0.1</unit_price>
        <quantity>10</quantity>
        <tax_rate>0.2</tax_rate>
        <tax_amount>20</tax_amount>
        <discount_rate>0</discount_rate>
        <discount_amount>0</discount_amount>
        <extended_amount>30</extended_amount>
        <line_item_id>123456</line_item_id>
      </purchases>
      <pos_data>
        <cardholder_presence>Ecom</cardholder_presence>
        <device_attendance>HomePc</device_attendance>
        <device_input_capability>Unknown</device_input_capability>
        <device_location>HomePc</device_location>
        <pan_capture_method>Manual</pan_capture_method>
        <partial_approval_support>NotSupported</partial_approval_support>
        <pin_capture_capability>Incapable</pin_capture_capability>
      </pos_data>
    </priority>
  </gateway_specific_fields>
</transaction>'
<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2022-04-20T15:31:50Z</created_at>
  <updated_at type="dateTime">2022-04-20T15:31:50Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>IJ5V7B3gEtuu3O3nHlpn2nEd3PD</token>
  <transaction_type>Purchase</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <priority>
      <source>Terminal</source>
      <invoice>123</invoice>
      <replay_id>8765</replay_id>
      <ship_amount>1</ship_amount>
      <ship_to_country>USA</ship_to_country>
      <ship_to_zip>27703</ship_to_zip>
      <source_zip>09873</source_zip>
      <customer_code>CUST98765</customer_code>
      <customer_name>testEnterprise</customer_name>
      <tax>0.03</tax>
      <vat_amount>0.02</vat_amount>
      <vat_rate>0.01</vat_rate>
      <duty_amount>0.03</duty_amount>
      <memo>priority</memo>
      <is_auth>true</is_auth>
      <tax_exempt>true</tax_exempt>
      <payment_type>Sale</payment_type>
      <tender_type>Card</tender_type>
      <purchases>
        <name>purchase name</name>
        <description>purchase description</description>
        <code>123</code>
        <unit_of_measure>unit</unit_of_measure>
        <unit_price>0.1</unit_price>
        <quantity>10</quantity>
        <tax_rate>0.2</tax_rate>
        <tax_amount>20</tax_amount>
        <discount_rate>0</discount_rate>
        <discount_amount>0</discount_amount>
        <extended_amount>30</extended_amount>
        <line_item_id>123456</line_item_id>
      </purchases>
      <pos_data>
        <cardholder_presence>Ecom</cardholder_presence>
        <device_attendance>HomePc</device_attendance>
        <device_input_capability>Unknown</device_input_capability>
        <device_location>HomePc</device_location>
        <pan_capture_method>Manual</pan_capture_method>
        <partial_approval_support>NotSupported</partial_approval_support>
        <pin_capture_capability>Incapable</pin_capture_capability>
      </pos_data>
    </priority>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>50</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2022-04-20T15:31:50Z</created_at>
    <updated_at type="dateTime">2022-04-20T15:31:50Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2022-04-20T15:29:52Z</updated_at>
    <email>[email protected]</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>String Value</key>
      <another_key>123</another_key>
      <final_key>true</final_key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

Gateway specific response fields

A response from the Priority gateway may contain a specific field which you can find in the gateway_specific_response_fields. For example:

  • reference
  • id
  • batch_id
<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <priority>
       <reference>123098</reference>
       <id>456789</id>
       <batch_id>abc1234</batch_id>
     </priority>
  </gateway_specific_response_fields>
</transaction>

To request any gateway_specific_fields or gateway_specific_response_fields, please contact Support with your request and the gateway documentation for the fields of interest.

Stored credentials

Priority supports card-on-file (COF) transactions. When you send a merchant-initiated recurring or
unscheduled transaction, Spreedly sends the posData values Priority requires to classify it correctly
under the card networks' stored credential rules.

Spreedly does not support the full stored credential framework on Priority.
Priority does not return a network transaction ID, so Spreedly cannot store one for a Priority
transaction or send one on later transactions in the chain. That also means a stored credential chain
started on Priority cannot be continued on another gateway, and a chain started elsewhere cannot be
continued on Priority. On this gateway, stored_credential_initiator and
stored_credential_reason_type are used only to build the posData object described below.
Spreedly will add full support once Priority makes the network transaction ID available.

To get the COF mapping, send all three of the following:

  • stored_credential_initiator set to merchant
  • stored_credential_reason_type set to recurring or unscheduled
  • the channel gateway specific field set to Moto or Ecom

Spreedly then sends the following posData values:

channelstored_credential_reason_typecardholderPresencedeviceAttendancedeviceInputCapabilitydeviceLocation
MotorecurringRecurringRecurringVoiceAruRecurring
MotounscheduledStandingVoiceAruVoiceAruVoiceAru
EcomrecurringRecurringRecurringKeyedOnlyRecurring
EcomunscheduledStandingHomePcKeyedOnlyHomePc

All four also send panCaptureMethod as OnFile, partialApprovalSupport as NotSupported,
pinCaptureCapability as Incapable, and transactionStatus as Normal.

If you omit channel, send any other value, or send a cardholder-initiated or installment transaction,
Spreedly sends its default posData instead:

pos_data subfieldposData field sent to PriorityDefault
cardholder_presencecardholderPresenceEcom
device_attendancedeviceAttendanceHomePc
device_input_capabilitydeviceInputCapabilityUnknown
device_locationdeviceLocationHomePc
pan_capture_methodpanCaptureMethodManual
partial_approval_supportpartialApprovalSupportNotSupported
pin_capture_capabilitypinCaptureCapabilityIncapable
transaction_statustransactionStatusnot sent

Any subfield you supply in the pos_data gateway specific field takes precedence, both over these defaults and over the card-on-file values above.

For how stored credential chains work across gateways, see Stored credentials.


Did this page help you?