API referenceiFrame APIExpress APISupportBlog
Guides

vPOS gateway guide

Suggest Edits

vPOS fact sheet

Adding a vPOS gateway

vPOS does not issue credentials to users who are not PCI certified, even if these users transact only through Spreedly.

Values for commerce and commerce_branch must be provided on gateway creation. These may be overriden on a per-transaction basis by using the gateway specific fields of the same name (see below.)

To add a vPOS gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>vpos</gateway_type>
        <public_key>Your public key</public_key>
        <private_key>Your private key</private_key>
        <commerce>123</commerce>
        <commerce_branch>45</commerce_branch>
      </gateway>'

<gateway>
  <token>P9wwNNuzzguNT5cmyNhmjhE7b8A</token>
  <gateway_type>vpos</gateway_type>
  <name>vPOS</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <public_key>Your public key</public_key>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">false</supports_authorize>
    <supports_capture type="boolean">false</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">false</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>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
  </characteristics>
  <credentials>
    <credential>
      <name>public_key</name>
      <value>Your public key</value>
    </credential>
  </credentials>
  <gateway_settings>
    <commerce_branch>45</commerce_branch>
    <commerce>123</commerce>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>commerce_branch</gateway_specific_field>
    <gateway_specific_field>commerce</gateway_specific_field>
    <gateway_specific_field>original_shop_process_id</gateway_specific_field>
    <gateway_specific_field>shop_process_id</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>
  <created_at type="dateTime">2021-07-26T14:29:14Z</created_at>
  <updated_at type="dateTime">2021-07-26T14:29:14Z</updated_at>
</gateway>

Setting the encryption_key

On or after gateway creation, we recommend setting a value for the gateway encryption_key. You may do this by extracting an encryption key from the transcript of your latest purchase transaction.

First, retrieve the transcript of the purchase transaction and look for a response from the gateway in the following format:

{"status":"success","encryption_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG[...]ywIDAQAB\n-----END PUBLIC KEY-----\n"}

Then update the gateway with the value returned for “encryption_key”. Make sure to include the final newline character (\n).

PUT /v1/gateways/<gateway_token>.json

{
  "gateway": {
    "encryption_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG[...]ywIDAQAB\n-----END PUBLIC KEY-----\n"
  }
}

Each time a transaction is made on a gateway without a value for encryption_key, a new encryption key will be requested from vPOS. This will invalidate the old key, and you will need to update the gateway again before executing any further purchase transactions. We recommend choosing a time for this update when transaction volume is expected to be low.

Gateway specific fields

When interacting with a vPOS gateway to run transactions, there are some gateway specific fields you can specify. A full example is below.

Note that refund and void transactions must be submitted with the same commerce and commerce_branch values as the original purchase transaction.

A unique shop_process_id is required for each vPOS transaction; if you do not supply one, Spreedly will randomly generate a value and return it in the response.

The value for original_shop_process_id will be automatically populated for refund and void transactions. You may optionally pass it with general_credit transactions.

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>
          <vpos>
            <commerce>123</commerce>
            <commerce_branch>45</commerce_branch>
            <shop_process_id>12345</shop_process_id>
            <original_shop_process_id>67890</original_shop_process_id>
          </vpos>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2021-08-04T16:22:21Z</created_at>
  <updated_at type="dateTime">2021-08-04T16:22:21Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>Mhxn0fWvsXAaHwUyiUyc6Wn7Hx6</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>
    <vpos>
      <commerce>123</commerce>
      <commerce_branch>45</commerce_branch>
      <shop_process_id>12345</shop_process_id>
      <original_shop_process_id>67890</original_shop_process_id>
    </vpos>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>65</gateway_transaction_id>
  <gateway_latency_ms type="integer">1</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">2021-08-04T16:22:21Z</created_at>
    <updated_at type="dateTime">2021-08-04T16:22:21Z</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">2021-08-04T16:07:28Z</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>
    </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 vPOS gateway may contain some of a number of specific fields which you can find in the gateway_specific_response_fields. These may change depending on whether or not the transaction is successful.

Successful transaction:

<transaction>
  <token>FfTT1vsDHE2VSZTiVr5Sh13jWcT</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <vpos>
      <shop_process_id>1234567</shop_process_id>
      <ticket_number>89012345</ticket_number>
      <authorization_number>123456</authorization_number>
      <response_code>00</response_code>
      <response_description>Transaccion aprobada</response_description>
    </vpos>
  </gateway_specific_response_fields>
</transaction>

Declined transaction:

<transaction>
  <token>FfTT1vsDHE2VSZTiVr5Sh13jWcT</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <vpos>
      <shop_process_id>1234567</shop_process_id>
      <ticket_number>89012345</ticket_number>
      <response_code>57</response_code>
      <response_description>Transaccion denegada</response_description>
      <extended_response_description>IMPORTE DE LA TRN INFERIOR AL M¿NIMO PERMITIDO</extended_response_description>
    </vpos>
  </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.

Updated 6 months ago