OpenPath Gateway Guide

OpenPath fact sheet

Additional notes
OpenPath processes USD transactions for merchants in the United States. Supported card brands are Visa, Mastercard, American Express, and Discover. OpenPath authenticates API requests using an OAuth bearer token obtained from your API Login ID and Transaction Key. Verify transactions perform an authorize followed by a void. OpenPath sandbox amounts under $1.00 may decline for purchase, authorize, and verify.

Additional notes

OpenPath processes USD transactions for merchants in the United States. Supported card brands are Visa, Mastercard, American Express, and Discover. OpenPath authenticates API requests using an OAuth bearer token obtained from your API Login ID and Transaction Key. Verify transactions perform an authorize followed by a void. OpenPath sandbox amounts under $1.00 may decline for purchase, authorize, and verify.

Quick start

New to integrating OpenPath with Spreedly? Here is your setup guide:

Retrieve your OpenPath credentials
1. Sign in to your OpenPath merchant account.
2. Collect your API Login ID and Transaction Key.
Get familiar with the Spreedly API
1. Review Spreedly API basics.
2. Understand Gateways, Payment Methods, and Transactions.
Add your OpenPath gateway to Spreedly in sandbox mode, then validate transactions.

ℹ️
Review this documentation to understand more about how to test transactions. See OpenPath test numbers for sandbox card and amount behavior.

Adding an OpenPath gateway

To add an OpenPath gateway, supply your API Login ID and Transaction Key.

Required credentials

api_login_id: API Login ID from your OpenPath merchant account.

transaction_key: Transaction Key from your OpenPath merchant account. This value is encrypted when stored in Spreedly.

Optional credentials or settings

No optional gateway settings are currently required for initial OpenPath provisioning.

Request

curl -X POST https://core.spreedly.com/v1/gateways.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "gateway": {
      "gateway_type": "openpath",
      "description": "OpenPath production",
      "api_login_id": "your-api-login-id",
      "transaction_key": "your-transaction-key"
    }
  }'

Response

{
  "gateway": {
    "token": "1GGR5AAJ038QSVPRTFGAHM8XTV",
    "gateway_type": "openpath",
    "name": "OpenPath",
    "description": "OpenPath production",
    "api_login_id": "your-api-login-id",
    "state": "retained",
    "characteristics": {
      "supports_purchase": true,
      "supports_authorize": true,
      "supports_capture": true,
      "supports_partial_capture": true,
      "supports_credit": true,
      "supports_partial_credit": true,
      "supports_void": true,
      "supports_verify": true,
      "supports_3dsecure_2_mpi_purchase": true,
      "supports_3dsecure_2_mpi_authorize": true,
      "supports_stored_credentials": true,
      "supports_store": true,
      "supports_remove": true,
      "supports_transaction_retry": true
    },
    "payment_methods": ["credit_card", "third_party_token"]
  }
}

Purchase

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 100,
      "currency_code": "USD",
      "description": "Store Purchase",
      "billing_address": {
        "name": "Jim Smith",
        "address1": "456 My Street",
        "address2": "Apt 1",
        "city": "Ottawa",
        "state": "ON",
        "zip": "K1C2N6",
        "country": "CA"
      }
    }
  }'

Authorize

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/authorize.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 100,
      "currency_code": "USD"
    }
  }'

Capture

Omit amount (or omit the request body) to capture the full authorized amount.

curl -X POST https://core.spreedly.com/v1/transactions/[authorization_token]/capture.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json'

Partial capture

Pass a lower amount to capture less than the authorized total.

curl -X POST https://core.spreedly.com/v1/transactions/[authorization_token]/capture.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "amount": 50
    }
  }'

Void

curl -X POST https://core.spreedly.com/v1/transactions/[authorization_token]/void.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json'

Credit (Refund)

Refunds are processed as credit transactions against a captured purchase.

curl -X POST https://core.spreedly.com/v1/transactions/[purchase_token]/credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "amount": 100
    }
  }'

Partial refund

curl -X POST https://core.spreedly.com/v1/transactions/[purchase_token]/credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "amount": 50
    }
  }'

Verify

OpenPath verify performs an authorize followed by a void.

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/verify.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "currency_code": "USD"
    }
  }'

Store

Store vaults a credit card at OpenPath and returns a Spreedly third_party_token payment method. Use the returned payment method token on subsequent purchase or authorize requests.

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/store.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "credit_card_payment_method_token",
      "currency_code": "USD"
    }
  }'

Response (abbreviated):

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Store",
    "gateway_type": "openpath",
    "payment_method": {
      "token": "stored_payment_method_token",
      "payment_method_type": "third_party_token",
      "third_party_token": "openpath-vault-token",
      "gateway_type": "openpath"
    }
  }
}

Purchase with stored token

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "stored_payment_method_token",
      "amount": 100,
      "currency_code": "USD"
    }
  }'

Unstore

Unstore removes the OpenPath payment token. You can run an unstore transaction or redact the stored payment method with remove_from_gateway set to the gateway token.

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/unstore.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "stored_payment_method_token"
    }
  }'

Redact with gateway removal:

curl -X PUT https://core.spreedly.com/v1/payment_methods/[stored_payment_method_token]/redact.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "remove_from_gateway": "[gateway_token]"
    }
  }'

Additional notes

Feature	Support status	Notes
Purchase / Authorize / Capture / Void / Credit / Verify	Supported	Includes partial capture and partial credit
3D Secure (3DS2 Global MPI)	Supported	Purchase and authorize
Stored credentials	Supported	Recurring, installment, and unscheduled
Transaction retry / decline salvage	Supported	Decline recapture GSFs on retry; salvage values in GSRFs
Vaulting (store/unstore)	Supported	Returns `third_party_token` payment methods
Billing address / email	Supported	Mapped on purchase, authorize, and store
Level II data (partial)	Supported	`surcharge` and `tip` GSFs on purchase and authorize
Level II/III data (full)	Not supported	Order-level `tax`, `shipping`, and `line_items` not exposed via Spreedly API
Apple Pay	Not supported	Not currently available for OpenPath in Spreedly
Google Pay	Not supported	Not currently available for OpenPath in Spreedly
Network tokenization	Not supported	Not currently available for OpenPath in Spreedly
Offsite / local payment methods	Not supported	Credit card and stored OpenPath tokens

Third-party 3DS2 MPI

ℹ️
Please review this guide to understand how Spreedly works with 3DS Global.

Spreedly maps third-party 3DS2 authentication data to OpenPath on purchase and authorize. After a successful 3DS authentication, pass the authentication values using Spreedly's standard three_ds fields.

Spreedly field	OpenPath field
`authentication_value` (`cavv`)	`cavv`
`xid`	`xid`
`ecommerce_indicator` (`eci`)	`eci` (zero-padded to two digits)
`version`	`three_ds_version`
`directory_server_transaction_id`	`directory_server_id`
`authentication_response_status`	`cardholder_auth` (`verified` when `Y`, `attempted` otherwise)

When OpenPath returns 3DS-related values on the gateway response, they may include cardholder_auth, cavv_result, eci, and liability_shift.

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 100,
      "currency_code": "USD",
      "three_ds_version": "2.2.0",
      "three_ds": {
        "authentication_value": "jJ81HADVRtXfCBATEp01CJUAAAA",
        "xid": "00000000000000000501",
        "ecommerce_indicator": "05",
        "directory_server_transaction_id": "97267598-FAE6-48F2-8083-C23433990FBC",
        "authentication_response_status": "Y"
      }
    }
  }'

Stored Credentials

OpenPath supports Spreedly's Stored Credentials framework on purchase and authorize. Include these fields on the transaction:

stored_credential_initiator — merchant or cardholder
stored_credential_reason_type — recurring, installment, or unscheduled

For subsequent merchant-initiated transactions, pass the network_transaction_id returned from the initial transaction.

1. First / credential-on-file setup (CIT and MIT initial)

`reason_type`	`initiator`	OpenPath mapping
`recurring`	`cardholder`	`detail.is_mit` = false; `detail.recurring.initial` = true
`recurring`	`merchant`	`detail.is_mit` = true; `detail.recurring.initial` = true
`installment`	`cardholder`	`detail.is_mit` = false; `detail.recurring.initial` = true
`installment`	`merchant`	`detail.is_mit` = true; `detail.recurring.initial` = true
`unscheduled`	`cardholder` or `merchant`	`detail.is_mit` from initiator; no recurring block on initial unscheduled

Optional CRM-style plan details can be supplied via the nested recurring gateway-specific field and merge into detail.recurring. The initial response may return a network_transaction_id for follow-on transactions.

2. Subsequent use (MIT)

`reason_type`	`initiator`	OpenPath mapping
`recurring`	`merchant`	`detail.recurring.initial` = false; `detail.recurring.id` = `network_transaction_id`
`installment`	`merchant`	`detail.recurring.initial` = false; `detail.recurring.id` = `network_transaction_id`
`unscheduled`	`merchant`	`network_schema_id` = `network_transaction_id`

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 100,
      "currency_code": "USD",
      "stored_credential_initiator": "cardholder",
      "stored_credential_reason_type": "recurring"
    }
  }'

Gateway Specific Fields

<gateway_specific_fields>
  <openpath>
    <gateway_specific_field>is_mit</gateway_specific_field>
    <gateway_specific_field>invoice_id</gateway_specific_field>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>decline</gateway_specific_field>
    <gateway_specific_field>device</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>surcharge</gateway_specific_field>
    <gateway_specific_field>tip</gateway_specific_field>
  </openpath>
</gateway_specific_fields>

is_mit: Explicit MIT flag. When omitted, Spreedly stored credential initiator still sets detail.is_mit.
invoice_id: Invoice or booking identifier mapped to OpenPath detail.invoice_id.
recurring: Nested object for CRM / plan details merged into OpenPath detail.recurring (for example name, recurring_type, payments, frequency_unit, frequency, billing_day, start_date, external_id, amount).
decline: Nested object used on transaction retry. Maps to OpenPath decline_recapture (code, description, source_type, source, avs_code, cvv_code, cavv_code, network_schema_id, network_schema).
device: Nested device telemetry object mapped to OpenPath detail.device as provided.
metadata: Flexible metadata object passed through to OpenPath as provided.
surcharge: Level II surcharge amount in cents, mapped to detail.surcharge.
tip: Level II tip amount in cents, mapped to detail.tip.

Field Name	Type	Required	Use Case (Description)	Example Value
is_mit	Boolean	No	Explicit merchant-initiated transaction flag sent to OpenPath `detail.is_mit`.	true
invoice_id	String	No	Invoice or booking identifier for merchant reconciliation.	BOOKING_OR_INVOICE_ID
recurring	Object	No	CRM / plan details merged into OpenPath `detail.recurring`. Nested keys may include `name`, `recurring_type`, `data_type`, `payments`, `frequency_unit`, `frequency`, `billing_day`, `start_date`, `external_id`, `initial`, and `amount`.	`{ "name": "Gold Plan", "recurring_type": "CRM", "payments": 12 }`
decline	Object	No	Prior-decline context for transaction retry. Nested keys: `code`, `description`, `source_type`, `source`, `avs_code`, `cvv_code`, `cavv_code`, `network_schema_id`, `network_schema`.	`{ "code": "201", "description": "Do not honor", "source": "issuer" }`
device	Object	No	Device telemetry passed through to OpenPath `detail.device` (for example `sense_key`, `type`, `name`, `os`, `browser`, `language`, `screen`, `timezone`, `user_agent`).	`{ "sense_key": "device-guid", "type": "MOBILE" }`
metadata	Object	No	Flexible merchant metadata passed through to OpenPath as provided.	`{ "MemberId": "MEMBER_ID", "BookingId": "BOOKING_ID" }`
surcharge	Integer	No	Level II surcharge amount in cents. Mapped to OpenPath `detail.surcharge`.	250
tip	Integer	No	Level II tip amount in cents. Mapped to OpenPath `detail.tip`.	150

Order-level tax, shipping, and line_items are not exposed via the Spreedly API for OpenPath.

curl -X POST https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 100,
      "currency_code": "USD",
      "gateway_specific_fields": {
        "openpath": {
          "invoice_id": "BOOKING_OR_INVOICE_ID",
          "surcharge": 250,
          "tip": 150,
          "device": {
            "sense_key": "device-guid",
            "type": "MOBILE",
            "name": "iPhone 15"
          },
          "decline": {
            "code": "201",
            "description": "Do not honor",
            "source": "issuer",
            "network_schema": "VISA"
          },
          "metadata": {
            "MemberId": "MEMBER_ID",
            "BookingId": "BOOKING_ID"
          }
        }
      }
    }
  }'

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <openpath>
    <status>Declined</status>
    <result_code>201</result_code>
    <result_message>201 | Do not honor</result_message>
    <decline_code>201</decline_code>
    <decline_description>Do not honor</decline_description>
    <decline_source>issuer</decline_source>
    <processor>NMI</processor>
    <processor_id>437</processor_id>
  </openpath>
</gateway_specific_response_fields>

status: OpenPath result status (for example Approved or Declined).
result_code: OpenPath result code.
result_message: OpenPath result message.
decline_code: Decline code returned by OpenPath for decline salvage workflows.
decline_description: Human-readable decline message from OpenPath.
decline_source: Decline source (for example, issuer or gateway).
processor: Processor or connector provider name from routing.
processor_id: Processor or connector ID from routing.

Field Name	Type	Description
status	string	OpenPath result status (for example `Approved` or `Declined`).
result_code	string	OpenPath result code.
result_message	string	OpenPath result message.
decline_code	string	Decline code returned by OpenPath for decline salvage workflows.
decline_description	string	Human-readable decline message from OpenPath.
decline_source	string	Decline source (for example, issuer or gateway).
processor	string	Processor or connector provider name from routing.
processor_id	string	Processor or connector ID from routing.

Fields are included only when OpenPath returns mapped values. Otherwise the openpath object may be empty or omitted. Treat all OpenPath gateway-specific response fields as optional.

Related Spreedly fields (not gateway-specific response fields):

gateway_transaction_id — OpenPath transaction ID from the authorization or purchase.
response.network_transaction_id — returned on initial recurring/installment stored credential transactions.
response.avs_code / response.cvv_code — AVS and CVV results from OpenPath.

On retry, pass decline salvage values from GSRFs back under nested gateway_specific_fields.openpath.decline on the next purchase or authorize.

Support and resources

ℹ️
OpenPath documentation: developer.openpath.io
API endpoint: https://api.openpath.io/v5 (production and sandbox)