---
title: "Create a store transaction"
method: POST
path: "/gateways/{gateway_token}/store"
tags: ["payment_methods"]
---

# Create a store transaction

`POST /gateways/{gateway_token}/store`

Tokenize a payment method *at the gateway*.

This transaction copies the payment method information from the Spreedly vault [to the gateway's vault](https://developer.spreedly.com/docs/third-party-vaulting) and creates a new Spreedly payment method to represent the gateway's version. The reference to the payment method at the gateway is called a ThirdPartyToken and is a separate payment method from the original payment method. It is up to you to manage the lifecycle of these linked payment methods – Spreedly does not keep them in sync in any way.

The ThirdPartyToken is locked to the gateway where the card is stored; it cannot be used at another gateway. If you'd like a card to be used at multiple gateways, you'll need to [retain the card in the Spreedly vault](https://developer.spreedly.com/docs/create-transactions#retain).

## Path parameters

- `gateway_token` string, required

## Request body

- Store
  - `transaction` object — Root request element
    - `payment_method_token` string, required — The token of the payment method to copy to the gateway
    - `sub_merchant_key` string — The token of the [sub-merchant](https://developer.spreedly.com/reference/create-sub-merchant) to associate with the current transaction. If an invalid `sub_merchant_key` is passed through, the value defaults to `null`
    - `currency_code` string — The currency of the funds, as [ISO 4217 alpha currency codes](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), e.g., `USD` for US dollars. Some gateways may need this for a store call but most do not.

## Response `200`

Created

- StoreResponse
  - `transaction` object — Root element
    - `created_at` string — The time the transaction was created
    - `currency_code` string — The currency of the funds, as [ISO 4217 alpha currency codes](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), e.g., `USD` for US dollars.
    - `updated_at` string — The time the transaction was last updated
    - `succeeded` boolean — `true` if the transaction request was successfully executed, `false` otherwise
    - `token` string — The token uniquely identifying this transaction at Spreedly
    - `state` string — The current state of the transaction
    - `gateway_specific_fields` string[] — The list of gateway specific fields that can be specified in supported gateway transactions
    - `gateway_specific_response_fields` object — A hash containing unique optional fields that a gateway may return based on certain customized options.
    - `transaction_type` string — The type of transaction
    - `third_party_token` string — The token identifying the payment method as it exists *at the gateway*
    - `gateway_transaction_id` string — The id of the transaction *at the gateway*. To be used when corresponding with the gateway or reconciling transactions
    - `gateway_latency_ms` string — The time it took the gateway to respond to Spreedly
    - `message_key` string — A machine-parseable string indicating the result of the transaction
    - `message` string — A human-readable string indicating the result of the transaction
    - `gateway_token` string — The token of the gateway to executed against
    - `gateway_type` string — The type (short name) of the gateway
    - `payment_method` ThirdPartyToken
      - `token` string — The Spreedly payment method token that references the payment method stored at the gateway
      - `created_at` string — The time the payment_method was created
      - `updated_at` string — The time the payment_method was last updated
      - `gateway_type` string — The type (short name) of the gateway.
      - `storage_state` string — The `storage_state` (retained, redacted, cached, used) of the payment method
      - `metadata` object — Metadata key-value pairs
      - `third_party_token` string — The token identifying the payment method as it exists *at the gateway*
      - `payment_method_type` string — The type of this payment method
    - `basis_payment_method` object — The payment method vaulted at Spreedly that was copied to the gateway as part of this transaction
    - `response` object — Unmodified details of the gateway response, including the `message` and `error_code`, if applicable. For failed transactions these fields can help determine the root cause
    - `sub_merchant_key` string — The token of the sub-merchant associated with the transaction.

## Other responses

- `401` — Unauthorized
- `422` — Unprocessable Entity

---

[API](https://skmtc.dev/spreedly/apis/spreedly-api-v1.md) · [All operations](https://skmtc.dev/spreedly/apis/spreedly-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spreedly/spreedly-api-v1/revisions/72ba4e23e65c/schema)